Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents.
QD 1 - 32-Bit QuickDraw: Version 1.2 Features
QuickDraw
Written by: Guillermo Ortiz April 1990
This Technical Note describes the changes and enhancements to 32-Bit QuickDraw from version 1.0 (as shipped on the original Color Disk) to version 1.2, which ships with System Software 6.0.5 and later. This Note assumes familiarity with Inside Macintosh, Volume V, Color QuickDraw, and 32-Bit QuickDraw release notes.
32-Bit QuickDraw
Version 1.0 of 32-Bit QuickDraw shipped in May 1989 in response to the growing need for Color QuickDraw support for direct color devices and pictures (PICT2) and video boards for large-screen monitors which require 32-bit addressing for black and white operation. This original version of 32-Bit QuickDraw was a separate file that had to be copied manually into the System Folder. With the introduction of the Macintosh IIci, Apple put 32-Bit QuickDraw into ROM. Now System Software 6.0.5 and later offer 32-Bit QuickDraw as an integral part of the System Software which can be installed by the standard Installer (although the file is still separate).
This Note describes the changes and enhancements in version 1.2 of 32-Bit QuickDraw from version 1.0. Beginning with version 1.2, QuickDraw functionality is identical on all Color QuickDraw machines, including all the performance improvements which were originally only available in the IIci ROM.
New Features (In No Particular Order)
PICTs Contain Font Name Information
Every time you draw text inside of an _OpenPicture and _ClosePicture pair, QuickDraw stores the name of the current font and uses it when playing back the picture. The opcode used to save this information is $002C and its data is as follows:
PictFontInfo = Record
length : Integer; { length of data in bytes }
fontID : Integer; { ID in the source system }
fontName : Str255;
END;
QuickDraw only saves this information one time for each font used in a picture. When QuickDraw plays back a picture, it uses the fontID as a reference into the list of font names which are used to set the correct font on the target system.
For example, the following code:
GetFNum('Venice', theFontID); { Set a font before opening PICT}
TextFont(theFontID);
pHand2 := OpenPicture (pictRect);
MoveTo(20,20);
DrawString(' Better be Venice');
GetFNum('Geneva', theFontID);
TextFont(theFontID);
MoveTo(20,40);
DrawString('Geneva');
GetFNum('New York', theFontID);
TextFont(theFontID);
MoveTo(20,60);
DrawString('New York');
GetFNum('Geneva', theFontID);
TextFont(theFontID);
MoveTo(20,80);
DrawString('Geneva');
ClosePicture;
generates a picture containing font information like this:
OpCode 0x002C {9,
"0005 0656 656E 6963 65"} /* save current font */
TxFont 'venice'
DHDVText {20, 20, " Better be Venice"}
OpCode 0x002C {9, /* save next font name */
"0003 0647 656E 6576 61"}
TxFont 'geneva'
DVText {20, "Geneva"}
OpCode 0x002C {11, /* ditto */
"0002 084E 6577 2059 6F72 6B"}
TxFont 'newYork'
DVText {20, "New York"}
TxFont 'geneva' /* second Geneva does not
need another $002C guy */
DVText {20, "Geneva"}
This feature works regardless of the type of picture being saved, including old style PICTs in a black and white port. Using _OpenCPicture instead of _OpenPicture to start a recording session results in the same functionality.
Direct PixPat Structures Now Supported
QuickDraw now supports 16-bit and 32-bit per pixel PixPat structures (patType = 1). In addition, it now supports a new patType (3) which uses dithering whenever 16-bit or 32-bit pixel patterns are displayed on indexed devices.
Direct 'cicn' Resources Now Supported
QuickDraw now supports 16-bit and 32-bit per pixel 'cicn' resources. The 16-bit per pixel is particularly cool since you save the space required for an 8-bit 'clut'.
GWorlds Can Now Be Allocated in MultiFinder Temporary Memory
You can now use the new useMFTempBit (bit 2) in a call to NewGWorld as an option to allocate pixels in MultiFinder temporary memory. In addition, you can now allocate screen buffers in MultiFinder temporary memory using the following routine, defined in Pascal and C:
FUNCTION NewTempScreenBuffer (globalRect: Rect; purgeable: BOOLEAN;
_CopyBits now supports the ditherCopy transfer mode whenever the destination device is between one and eight bits per pixel, regardless of the depth of the source image. With this support, an eight-bit image can now be approximated on a one-bit or a four-bit device by using error diffusion. Furthermore, an eight-bit image could also be dithered to a different set of 256 colors or a four-bit image could be dithered to an eight-bit device that does not have the desired colors.
32-Bit Addressed PixMap Structures
Version 1.2 defines a new pmVersion (baseAddr32 = 4) for 32-bit pointer baseAddr values. The baseAddr of such PixMap structures is treated as a 32-bit address, so no stripping or address translation is performed on it in 32-bit mode. This is a specially useful feature when the base address of a PixMap points to a NuBus™ address, for example in a video grabber board.
A new call, Pixmap32Bit, is now available to inquire if a given PixMap requires 32-bit addressing.
Version 1.2 updates GetPixBaseAddress to return the address of any PixMap. The routine does the right address translation or stripping for all PixMap structures, including screen devices, unlocked GWorlds, and 32-bit addressed PixMap structures. The address it returns is only valid in 32-bit addressing mode. Also unless the PixMap is locked and made unpurgeable, the address returned by GetPixBaseAddress is only valid until any call to QuickDraw or the toolbox is made.
_CopyBits from Screen Devices
The picture recording mechanism has changed so that if you call _CopyBits while recording a picture with the source PixMap being a screen device, the data is correctly accumulated into the picture. Note that if the screen being copied is not the main screen, then the PixMap must be a 32-bit addressed PixMap. No auxiliary screen buffer is allocated if the source rectangle covers only one screen.
New Picture Recording Trap
Version 1.2 adds a new call, _OpenCPicture, to create pictures that contain information regarding the native resolution of the recorded image. When QuickDraw draws this picture, it scales the image to the resolution of the target device. Applications that need to scale the images directly can also access this information.
FUNCTION OpenCPicture(VAR CPictInfo:CPictRecord):PicHandle;
For information on bug fixes in the System Software 6.0.5 release of 32-Bit QuickDraw (version 1.2), please refer to the System Software 6.0.5 Change History, which is available on the Developer CD Series, AppleLink in the Developer Services Bulletin Board (Developer Services: Macintosh Developer Technical Support: System Software), and the Apple FTP site on the Internet in the ~ftp/pub/dts/sw.license.
Note that the dispatching mechanism for the new _QDOffscreen calls is slightly different than previously documented; it now requires that the high word passed in D0 contain the total length of the parameters (in bytes). The reason for this change is that if the call is made in an earlier version of 32-Bit QuickDraw, the system can strip the parameters from the stack and return QDError set to the caller (instead of crashing).
Further Reference:
• Inside Macintosh, Volume V, Color QuickDraw
• 32-Bit QuickDraw Release Notes (available from APDA)
• System Software 6.0.5 Change History
• d e v e l o p, Issue I
NuBus is a trademark of Texas Instruments.
QD 2 - BitMapToRegion : So Many Bitmaps, So Little Time
QuickDraw
Revised by: Rich Collyer December 1989
Written by: Rick Blair April 1988
This Technical Note discusses the routine BitMapToRegion, which converts a bitmap to a region, and is available in the 32-Bit QuickDraw INIT and from Apple Software Licensing.
Changes since October 1989: Added trap definitions for developers using the 32-Bit QuickDraw version of this routine without the correct MPW include file.
The following routine is now available to convert a bitmap to a region:
FUNCTION BitMapToRegion(region:RgnHandle; bMap:BitMap): OSErr;
If you are using the 32-Bit QuickDraw version of this routine without the correct MPW include file, then you need to include one of the following definitions:
Pascal
FUNCTION BitMapToRegion (region: RgnHandle; bMap: BitMap): OSErr;
The region will be built so that all one bits in bMap are inside the region and all zero bits are outside of it.
As with all QuickDraw calls which change a region, BitMapToRegion requires you to pass an existing region (originally created by _NewRgn). If the region cannot be built due to an insufficient heap space or a size greater than 32K, then the routine will return an appropriate error code and the region will be empty. If the region would have exceeded 32K, the error will be rgnTooBigErr (-500).
This function is useful for a number of situations where you have (or can produce) a bitmap representing an area. You can use _CalcMask to produce such a bitmap. Once you have a region, you can perform region operations (i.e., _PtInRgn, _UnionRgn, or _InsetRgn) or call _DragGrayRgn, for example.
This call is part of the 32-Bit QuickDraw INIT ($A8D7). If you do not wish to depend on 32-Bit QuickDraw, then you can obtain a version of BitMapToRegion in MPW object format which can be linked into an MPW program, by contacting Apple Software Licensing:
Apple Software Licensing
Apple Computer, Inc.,
20525 Mariani Avenue, M/S 38-I
Cupertino, CA, 95014
(408) 974-4667
AppleLink: SW.LICENSE
If you licensed the older version of this routine, BitMapRgn, contact Software Licensing about receiving an updated version. We recommend you update your application to use the new version as soon as possible.
The new version is now named BitMapToRegion to be consistent with the version in 32-Bit QuickDraw and the MPW interfaces. In addition, BitMapToRegion offers new features. You can now pass a one-bit pixelmap which has been coerced to a bitmap. If you pass a pixelmap which is too large, then you will get a pixmapTooDeepErr (-148) error. You can also pass the portBits of a window, much like you would do with a call to _CopyBits.
There is a potential problem with this routine, since MPW 3.1 include files contain information about 32-Bit QuickDraw. If you want BitMapToRegion to be available on all machines, then you must use the object file from Software Licensing. The problem is that when you compile your application with MPW 3.1 or later, the 32-Bit QuickDraw version gets preference over the object file. You must comment out the routine in the include files if you want to use the object file. If you only care about using BitMapToRegion on machines running 32-Bit QuickDraw, then you need not do anything.
QD 3 - Color Cursor Cursing : A Leading Cause
QuickDraw
Revised by: Alan Mimms October 1989
Written by: Alan Mimms June 1989
Working with color cursors you create from scratch can cause headaches. This Technical Note may help a bit.
Changes since June 1989: Added a warning about purgeable 'clut' resources.
If you’re building an application that creates color cursors, you may encounter some quirks present in Color QuickDraw that manifest themselves in hard-to-understand ways.
If your cursor is, say, 15 pixels tall and 9 pixels wide, you might be tempted to use these values for the bounds.bottom and bounds.right, respectively, in your cursor’s pixel map. Don’t. The problem is that when the cursor’s image needs to be expanded (i.e., when you specify a two bit-per-pixel cursor and the mouse pointer is on an eight-bit screen) the _SetCCursor trap rounds the width of the pixel map in such a way that you’ll get only the space required for a 15 by 8 pixel map allocated for the expanded cursor data. When the cursor’s image is expanded into this too-small expanded cursor data handle as a 15 by 9 pixel map, something in your heap will get munched.
The cure is simple. Make certain that you always specify that the pixmapHandle^^.bounds be 16 by 16. This will cause _SetCCursor to properly allocate the expanded data area, and all will be well in the land. Since the amount of data drawn for a cursor is specified by the cursor’s pixel values and 'clut' resource, trying to save a few bytes by making the bounds rectangle smaller than 16 by 16 wouldn’t have been very helpful anyway.
Another potential problem is with the color cursor’s color table. If you load the color table from a 'clut' resource using _GetCTable, you should make sure that the 'clut' is marked non-purgeable while the color cursor is in use. If you do not take this precaution, bombs will occur if your 'clut' gets purged at in inopportune time.
QD 4 - Colorizing With CopyBits
QuickDraw
Revised by March 1988
Written by: Chris Derossi November 1987
Inside Macintosh Volume V states that the foreground and background colors are applied to an image during a CopyBits or CopyMask call. Accidental use of this feature can create bizarre coloring effects. This note explains what happens, how to avoid problems, and how to use it.
What Happens
Color QuickDraw has a feature that will allow you to convert a monochrome image to a color image. During a CopyBits or CopyMask call, if the foreground and background colors are not black and white, respectively, Color QuickDraw performs the following operation on every pixel being copied:
NOTE: color table index = pixel value
s = color table index of source pixel
fg = color table index of foreground color
bg = color table index of background color
ColoredPixelValue = (NOT(s) AND bg) OR (s AND fg)
If your source image contains only black and white pixels, then all black pixels would become the foreground color and all white pixels would become the background color. This is because the color table index for white is all zeros and the color table index for black is all ones.
For example, suppose your source image was a 4-bit deep color PixMap. Then the color table index for white (in binary) is 0000 and the index for black is 1111. And let’s suppose that your foreground color is green with an index of 1101 while your background color is red with an index of 0011. Then for the black pixels, the above procedure produces:
ColoredPixelValue = (NOT(1111) AND 0011) OR (1111 AND 1101)
1101 = ( 0000 AND 0011) OR (1111 AND 1101)
And the operation on the white pixels yields:
ColoredPixelValue = (NOT(0000) AND 0011) OR (0000 AND 1101)
0011 = ( 1111 AND 0011) OR (0000 AND 1101)
Possible Problems
This colorizing will only work on 2-color (i.e. black and white) images, and then only if those colors occupy the first and last entries in the color table. Trying to colorize colors that are not the first and last color table entries will yield unexpected results.
This is mainly due to the fact that the colorizing algorithm uses a pixel’s color table index value rather than its actual RGB color. To illustrate this, let’s assume that foreground and background colors are as above, and your image contains yellow with a color table index of 1000. The colorizing operation would give:
ColoredPixelValue = (NOT(1000) AND 0011) OR (1000 AND 1101)
1011 = ( 0111 AND 0011) OR (1000 AND 1101)
Since the color table may have any RGB color at the resulting index position, the final color may not even be close to the source, foreground, or background colors.
Similar things occur if you are trying to colorize a black and white image when white and black do not occupy the first and last positions in the color table.
The bottom line rules for CopyBitsing in a color environment are these:
• Thou shalt set thy background color to white and thy foreground color to black before calling CopyBits or CopyMask, unless thou art coloring a monochrome image.
• Thou shalt, when colorizing, make sure that the first color table entry is white and the last color table entry is black.
The second rule is easy to follow because the default color tables are constructed properly, and if you are using the Palette Manager (and you are, right?) then it will make sure that the color tables obey this rule.
How To Colorize—An Example
This code fragment shows how to implement a color fill, like the paint bucket in MacPaint. It relies on three main things: SeedCFill for calculating the fill area, CopyMask for actually changing the bits, and QuickDraw colorizing.
The variable offBits is an offscreen BitMap (not a PixMap) with bounds = myWindow^.portRect. SeedCFill effectively creates, in the offscreen BitMap, a monochrome image of the bits that we want to paint. Since offBits contains the exact bits that we want to paint, it is used as both the source image and the mask for CopyMask.
By setting the foreground color to the desired paint color, the result is a colorized version of the mask (the paint area) being copied onto the window’s PixMap without affecting any other bits.
Further Reference:
• Color QuickDraw
QD 5 - Displaying Large PICT Files
QuickDraw
Revised by: March 1988
Written by: Rick Blair July 1987
Now that we have scanners and other massive-picture producing types of applications, there is a need to address the problem of how to display a PICT format object that is bigger than a current PICT resource is allowed to be. Note that this technique applies equally well to version 1 and version 2 (word-opcode) pictures as produced by the Macintosh II.
Future Compatibility
Think of the handle returned by a GetResource('PICT',ID) as a “handle” in the more general sense of being an abstract “tag”—something that the ROM routines can use to draw the picture with. Don’t assume that the entire picture has been read into memory or that you can directly read any bytes beyond the basic Picture record structure (picSize followed by picFrame). Someday we may provide a mechanism for the resource to be disk- instead of memory-based. The QuickDraw bottleneck procedures will know how to get data from and put data into the pictures in any case.
Spooling from a PICT file
In order to display pictures of arbitrary size, your application should be able to import a QuickDraw picture from a file of type PICT. This is the file produced by a “Save as…” from MacDraw with the PICT option selected.
What follows is a small program fragment that demonstrates how to spool in a picture from [the data fork of] a PICT file. The picture can be larger than the historical 32K resource size. See technical note #88 if you are unfamiliar with the Signal mechanism. We assume that a CatchSignals has been done before GetandDrawPICTFile is called.
MPW Pascal Example
{the following variable must be at the top level}
VAR
globalRef : INTEGER; {refNum of the file to read from}
{the following procedure must be at the top level}
DrawPicture(myPicture,&(**myPicture).picFrame); /*draw the picture*/
err = GetFPos(globalRef,&filePos);/*get position for check*/
if (err != noErr) return err;
err = FSClose(globalRef);
if (err != noErr) return err;
DisposHandle((Handle)myPicture);
(*qd.thePort).grafProcs = savedProcs;/*restore the procs*/
/*Check for errors. if there wasn't enough room,*/
/*DrawPicture will abort; the FILE position mark*/
/*won't be at the end of the FILE.*/
if (filePos != myEOF) return abortPICT;
else return noErr;
} /*if (reply.good) */
} /* GetDrawPICTFile */
More on Picture Compatibility
Many applications already support PICT resources larger than 32K. The 128K ROMs (and later) allow pictures as large as memory (or spooling) will accommodate. This was made possible by having QuickDraw ignore the size word and simply read the picture until the end-of-picture opcode was reached.
For maximum safety and convenience, let QuickDraw generate and interpret your pictures.
While Apple has provided you with the data formats that allow you to read or write picture data directly, we recommend that you always let DrawPicture or OpenPicture and ClosePicture process the opcodes.
One reason to read a picture directly by scanning the opcodes would be to disassemble it to, for example, extract a Color QuickDraw pixel map to save off in a private data structure. This shouldn’t normally be necessary.
If you do look at the picture data be sure and check the version information. You may want to put up an alert in your application that indicates to the user when a picture was created using a later version of the picture format than your application recognizes, letting them know that some elements of the picture cannot be displayed. If the version information indicates a QuickDraw picture version later than the one recognized by your application, your program should skip over the new opcodes and only attempt to parse the ones it knows.
As with reading picture data directly, it is best to use QuickDraw to create data in the PICT format. If you do need to create PICT format data directly, it is essential that you use the latest opcode specifications and that you thoroughly test the data produced on both color and black and white Macintosh machines. Contact Macintosh Developer Technical Support if you are not sure that you have the latest specifications.
Apple does not guarantee that a picture which wasn’t produced by QuickDraw will work.
Further Reference:
• QuickDraw
• Technical Note M.IM.PictureOpcodes —
Internal Picture Format
• Technical Note M.PT.Signals —
Signals
QD 6 - Every Picture [Comment] Tells Its Story, Don’t It?
QuickDraw
Revised by: March 1988
Written by: Rick Blair November 1987
Application-specific picture comment conflict and registration is addressed, along with Developer Technical Support’s method for solving it.
I will assume that the nature and usefulness of picture comments are already well known. The problem I am addressing is that, as it stands, developers must register their comments with us (Developer Technical Support) or run the risk of using the same comments as those used by Apple or within another third party product.
The idea here is to provide a “metacomment” which will contain information about which application owns the comment as well as the comment itself:
data = application signature (i.e. 'MPNT' for MacPaint) = 4 bytes
application “local” kind = 2 bytes
comment data = n bytes
In this way each comment may be specific to an application. It is still up to a developer to publish information about the comments they have defined if they wish them to be understood and used by other programs.
Previously assigned and registered comments will still be valid. This means that those defined for the LaserWriter or MacDraw, for instance, will retain their normal meaning.
Suppose your application (creator = 'MYAP') wanted to define a comment. The appearance of the comment would be as follows (assuming you chose 128 to be the “local” kind for the comment):
kind = 100; data = 'MYAP' [4 bytes] + 128 [2 bytes] + additional data
Further Reference:
• QuickDraw
• Technical Note M.IM.PictComments —
Optimizing for the LaserWriter—Picture Comments
QD 7 - Off-Screen Bitmaps
QuickDraw
Revised by: Jon Zap & Forrest Tanaka June 1990
Written by: Jim Friedlander & Ginger Jernigan July 1985
This Technical Note provides an example of creating an off-screen bitmap, drawing to it, and then copying from it to the screen.
Changes since April 1990: Clarified the section on window updates with off-screen bitmaps to explicitly limit these updates to your own windows.
The following is an example of creating and drawing to an off-screen bitmap, then copying from it to an on-screen window. We supply this example in both MPW Pascal and C.
MPW Pascal
First, let’s look at a general purpose function to create an off-screen bitmap. This function creates the GrafPort on the heap. You could also create it on the stack and pass the uninitialized structure to a function similar to this one.
FUNCTION CreateOffscreenBitMap(VAR newOffscreen:GrafPtr; inBounds:Rect) : BOOLEAN;
VAR
savePort : GrafPtr;
newPort : GrafPtr;
BEGIN
GetPort(savePort); {need this to restore thePort after OpenPort changes it}
newPort := GrafPtr(NewPtr(sizeof(GrafPort))); {allocate the GrafPort}
IF MemError <> noErr THEN BEGIN
CreateOffscreenBitMap := false; {failed to allocate it}
EXIT(CreateOffscreenBitMap);
END;
{
the OpenPort call does the following . . .
allocates space for visRgn (set to screenBits.bounds) and clipRgn (set wide
open)
sets portBits to screenBits
sets portRect to screenBits.bounds
etc. (see IM I-163,164)
side effect: does a SetPort(offScreen)
}
OpenPort(newPort);
{make bitmap exactly the size of the bounds that caller supplied}
WITH newPort^ DO BEGIN {portRect, clipRgn, and visRgn are in newPort}
portRect := inBounds;
RectRgn(clipRgn, inBounds); {avoid wide-open clipRgn, to be safe}
RectRgn(visRgn, inBounds); {in case inBounds is > screen bounds}
END;
WITH newPort^.portBits DO BEGIN {baseAddr, rowBytes and bounds are in
newPort}
bounds := inBounds;
{rowBytes is size of row It must be rounded up to even number of bytes}
ClosePort(oldOffscreen); { dump the visRgn and clipRgn }
DisposPtr(oldOffscreen^.portBits.baseAddr); { dump the bits }
DisposPtr(Ptr(oldOffscreen)); { dump the port }
END;
Now that you know how to create and destroy an off-screen bitmap, let’s go through the motions of using one. First, let’s define a few things to make the _NewWindow call a little clearer.
CONST
kIsVisible = true;
kNoGoAway = false;
kMakeFrontWindow = -1;
myString = 'The EYE'; {string to display}
Here’s the body of the test code:
VAR
offscreen : GrafPtr; {our off-screen bitmap}
ovalRect : Rect; {used for example drawing}
myWBounds : Rect; {for creating window}
OSRect : Rect; {portRect and bounds for off-screen bitmap}
myWindow : WindowPtr;
BEGIN
InitToolbox; {exercise left to the reader}
myWBounds := screenBits.bounds; { size of main screen }
InsetRect(myWBounds, 50,50); { make it fit better }
DestroyOffscreenBitMap(offscreen); {remove the evidence}
WHILE NOT Button DO; {give user a chance to see the results}
END.
MPW C
First, let’s look at a general purpose function to create an off-screen bitmap. This function creates the GrafPort on the heap. You could also create it on the stack and pass the uninitialized structure to a function similar to this one.
Boolean CreateOffscreenBitMap(GrafPtr *newOffscreen, Rect *inBounds)
{
GrafPtr savePort;
GrafPtr newPort;
GetPort(&savePort); /* need this to restore thePort after OpenPort */
newPort = (GrafPtr) NewPtr(sizeof(GrafPort)); /* allocate the grafPort */
if (MemError() != noErr)
return false; /* failed to allocate the off-screen port */
/*
the call to OpenPort does the following . . .
allocates space for visRgn (set to screenBits.bounds) and clipRgn (set wide
open)
sets portBits to screenBits
sets portRect to screenBits.bounds
etc. (see IM I-163,164)
side effect: does a SetPort(&offScreen)
*/
OpenPort(newPort);
/* make bitmap the size of the bounds that caller supplied */
newPort->portRect = *inBounds;
newPort->portBits.bounds = *inBounds;
RectRgn(newPort->clipRgn, inBounds); /* avoid wide-open clipRgn, to be safe */
RectRgn(newPort->visRgn, inBounds); /* in case newBounds is > screen bounds */
/* rowBytes is size of row, it must be rounded up to an even number of bytes */
if (MemError()!=noErr) { /* check to see if we had enough room for the bits */
SetPort(savePort);
ClosePort(newPort); /* dump the visRgn and clipRgn */
DisposPtr((Ptr)newPort); /* dump the GrafPort */
return false; /* tell caller we failed */
}
/* since the bits are just memory, let's clear them before we start */
EraseRect(inBounds); /* OpenPort did a SetPort(newPort) so we are ok */
*newOffscreen = newPort;
SetPort(savePort);
return true; /* tell caller we succeeded! */
}
Here is the function to get rid of an off-screen bitmap created by the previous function:
void DestroyOffscreenBitMap(GrafPtr oldOffscreen)
{
ClosePort(oldOffscreen); /* dump the visRgn and clipRgn */
DisposPtr(oldOffscreen->portBits.baseAddr); /* dump the bits */
DisposPtr((Ptr)oldOffscreen); /* dump the port */
}
Now that you know how to create and destroy an off-screen bitmap, let’s go through the motions of using one. First, let’s define a few things to make the _NewWindow call a little clearer.
#define kIsVisible true
#define kNoGoAway false
#define kNoWindowStorage 0L
#define kFrontWindow ((WindowPtr) -1L)
Here’s the body of the test code:
main()
{
char* myString = "\pThe EYE"; /* string to display */
GrafPtr offscreen; /* our off-screen bitmap */
Rect ovalRect; /* used for example drawing */
Rect myWBounds; /* for creating window */
Rect OSRect; /* portRect and bounds for off-screen bitmap*/
WindowPtr myWindow;
InitToolbox(); /* exercise for the reader */
myWBounds = qd.screenBits.bounds; /* size of main screen */
InsetRect(&myWBounds, 50,50); /* make it fit better */
DestroyOffscreenBitMap(offscreen); /* dump the off-screen bitmap */
while (!Button()); /* give user a chance to see our work of art */
}
Comments
In the example code, the bits of the BitMap structure, which are pointed to by the baseAddr field, are allocated by a _NewPtr call. If your off-screen bitmap is close to the size of the screen, then the amount of memory needed for the bits can be quite large (on the order of 20K for the Macintosh SE or 128K for a large screen). This is quite a lot of memory to lock down in your heap and it can easily lead to fragmentation if you intend to keep the off-screen bitmap around for any length of time. One alternative that lessens this problem is to get the bits via _NewHandle so the Memory Manager can move them when necessary. To implement this approach, you need to keep the handle separate from the GrafPort (for example, in a structure that combines a GrafPort and a Handle). When you want to use the off-screen bitmap you would then lock the handle and put the dereferenced handle into the baseAddr field. When you are not using the off-screen bitmap you can then unlock it.
This example does not demonstrate one of the more typical uses of off-screen bitmaps, which is to preserve the contents of windows so that after a temporary window or dialog box obscures part of your windows and is then dismissed, you can quickly handle the resulting update events without recreating all of the intermediate drawing commands.
Make sure you only restore the pixels within the content regions of your own windows in case the temporary window partly obscures windows belonging to other applications or to the desktop. Another application could change the contents of its windows while they are behind your temporary window, so you cannot simply restore all the pixels that were behind the temporary window because that would restore the old contents of the other application’s windows. Instead, you could keep keep an off-screen bitmap for each of your windows and then restore them by copying each bit map into the corresponding window’s ports when they get their update events.
An alternate method is to make a single off-screen bitmap that is as large as the temporary window and a region that is the union of the content regions of your windows. Before you display the temporary window, copy the screen into the off-screen bit map using the region as a mask. After the temporary window is dismissed, restore the obscured area by copying from the off-screen bit map into a copy of the Window Manager port, and use the region as a mask. If the region has the proper shape and location, it prevents _CopyBits from drawing outside of the content regions of your windows. See Technical Note #194, WMgrPortability for details about drawing across windows.
In some cases it can be just as fast and convenient to simply define a picture (PICT) and then draw it into your window when necessary. There are cases, however, such as text rotation, where it is advantageous to do the drawing off the screen, manipulate the bit image, and then copy the result to the visible window (thus avoiding the dangers inherent in writing directly to the screen). In addition, this technique reduces flicker, because all of the drawing done off the screen appears on the screen at once.
It is also important to realize that, if you plan on using the pre-Color QuickDraw eight-color model, an off-screen bitmap loses any color information and you do not see your colors on a system that is capable of displaying them. In this case you should either use a PICT to save the drawing information or check for the presence of Color QuickDraw and, when it is present, use a PixMap instead of a BitMap and the color toolbox calls (Inside Macintosh, Volume V) instead of the standard QuickDraw calls (Inside Macintosh, Volume I).
You may also want to refer to the OffScreen library (DTS Sample Code #15) which provides both high- and low-level off-screen bitmap support for the 128K and later ROMs. The OffSample application (DTS Sample Code #16) demonstrates the use of this library.
Further Reference:
• Inside Macintosh, Volumes I & IV, QuickDraw
• Inside Macintosh, Volume V, Color QuickDraw
• Technical Note M.IM.PrincipiaOffscreen —
Principia Off-Screen Graphics Environments
• Technical Note M.TB.WMgrPort —
WMgrPortability
• DTS Macintosh Sample Code #15, OffScreen & #16, OffSample
QD 8 - Old-Style Colors
QuickDraw
Revised by: Bill Guschwan May 1993
Written by: Rich “I See Colors” Collyer and Byron Han October 1989
This Technical Note covers limitations of the original Macintosh color model (eight-color) that Inside Macintosh Volume I, page I-173, QuickDraw, does not document.
Changes since October 1989:
Added definitions of the old-style constants.
Corrected definitions of old-style constants to reflect MPW 3.2 interfaces.
QuickDraw has always been able to deal with color, just on a very limited basis. Most applications have not made use of this feature, since Color QuickDraw–based Macintosh computers come with a better color model. There are, however, a few nice features that come with the old-style color model. With the old-style colors, it is easy to print color on an ImageWriter with a color ribbon. Another advantage is that developers do not have to write special-case code depending on whether or not a machine has Color QuickDraw.
Now that you are ready to convert to the old-style colors, there are a few things you should know about that do not work with old-style colors. This Note covers the limitations of using old-style colors, as well as the best ways to work around these limitations.
Limitations
The most obvious limitation is that of only eight colors: black, white, red, green, blue, cyan, yellow, and magenta. This limitation is a problem only if you want to produce a color-intensive application; if this describes your application, then you need not read any further in this Note.
The next limitation is that off-screen buffers are not very useful. You can draw into off-screen buffers, but there is no way to get the colors back from the buffer. This leads into the next limitation, which is that _CopyBits cannot copy more than one color at a time.
When you call _CopyBits from an off-screen buffer to your window, you need to set the forecolor to the color you want to copy before calling _CopyBits (for example, to copy a red object, call _ForeColor(redColor)). Now when you copy the object, you can copy only one color. If you copy different colored objects at one time, then you have a problem. The result of a multicolored copy is that all objects copy in the same color, that of the foreground.
It is possible to work with an off-screen buffer and the old-style colors, but it requires a lot of extra work. Unless the objects are really complex, then it is probably easier to just draw the objects directly into your window.
One other limitation does exist. Consider the following code sample. One would assume that this sample would work at all times.
SetPort (myPort);
savedFG := myPort^.fgColor;
ForeColor (redColor); {or any other color}
{...drawing takes place here...}
ForeColor (savedFG);
Surprise. It does not always work. The saved value for the fgColor field of the grafPort is not a classic QuickDraw color if the grafPort is actually a cGrafPort. If dealing with a cGrafPort, the fgColor field actually contains the foreground color’s entry in the color table, so the second call to _ForeColor really messes things up.
The proper way to set and reset the foreground color with classic QuickDraw’s _ForeColor call is as follows:
SetPort (myPort);
savedFG := myPort^.fgColor;
ForeColor (redColor); {or any other color}
{...drawing takes place here...}
myPort^.fgColor := savedFG; {Manually stuff the old fgColor back.}
If (32BQD = TRUE) Then {32BQD is a flag that is made and set by}
PortChanged (myPort); {the application; to set it, the application}
{needs to check _Gestalt for 32-Bit QuickDraw.}
This Note also applies to the routine _BackColor.
What Works
The easiest way to work with these limited colors is to use pictures. When you draw the images, you should draw into a picture. Then when you want to draw the images into your window or to a printer, call _DrawPicture. Pictures work well with the old-style colors, and you don’t need to worry about making sure that the forecolor is current when you draw into your window.
Once you have the picture, you can use it to draw into the screen or to the printer port. You can also set the WindowRecords windowPic to equal your PictureHandle so updates are handled by the Window Manager.
What Do Those Constants Mean Anyway
The correct values are
blackColor = 33
whiteColor = 30
redColor = 205
greenColor = 341
blueColor = 409
cyanColor = 273
magentaColor= 137
yellowColor = 69
The following discussion is theoretical and was based on the color constants for the MPW 3.1 interfaces. Well, those interfaces were wrong as far as the color constants. The discussion will be kept here to prove once and for all that Macintosh programming sometimes is arbitrary and not logical. On the other hand, the information about the color bits is correct.
Each of the constants contains 9 bits of information, and each bit has a special meaning. Figure 1 illustrates the meaning of each of the bits, while Table 1 shows how each of the color constants fills in the appropriate bits.
Figure 1—Bit Definitions
Table 1 Color-Bit Correlation
black white red green blue cyan magenta yellow
(33) (30) (209) (329) (389) (269) (149) (89)
Cyan 0 0 0 1 1 1 0 0
Magenta 0 0 1 0 1 0 1 0
Yellow 0 0 1 1 0 0 0 1
Black 1 0 0 0 0 0 0 0
Red 0 1 1 0 0 0 1 1
Green 0 1 0 1 0 1 0 1
Blue 0 1 0 0 1 1 1 0
Inverse 0 1 0 0 0 0 0 0
Normal 1 0 1 1 1 1 1 1
Further Reference:
• Inside Macintosh, Volume I, page I-173, QuickDraw
• Technical Note M.IM.Copybits—Of Time and Space and _CopyBits
QD 9 - Palette Manager Changes in System 6.0.2
QuickDraw
Written by: Guillermo Ortiz October 1988
This Technical Note describes the changes and enhancements to the Palette Manager in System Software 6.0.2 and future versions.
Application Palette
Applications now have the ability to define a default palette for the system to use when it needs to define the color environment (i.e., when it creates a color window without an associated palette or displays a dialog box).
The application palette feature is especially cool in cases where a color application uses old-style dialogs and alerts because without an application palette, the system will use the default palette to define the color environment. Since the system uses the default palette, the color environment may change (will change in 16-color mode) to cause some “cosmic” colors to appear in the active window. Defining a default application palette with two colors, black and white, solves this problem.
If the system needs a palette to define a color environment, it looks in the resource fork of the application for the 'pltt' ID = 0 resource and uses the palette which it contains. If the system cannot find this resource in the application’s resource fork, it will use its own default palette (resource 'pltt' ID = 0 in the System file) if present, or, if necessary, it will use the Palette Manager’s built-in palette.
Once an application has set its color environment (by calling _InitMenus, or _InitPalettes in weird instances when there are no menus) it can find the default palette by calling GetPalette ( WindowPtr (-1) ) or change the default palette by calling SetPalette ( WindowPtr (-1), newDefPltt, true ). Note that the initialization of the Palette Manager with a call to _InitMenus is contrary to the way Inside Macintosh, Volume V, The Palette Manager documents it.
One Palette, Many Ports
You can now associate one palette with many CGrafPort and CWindow records, thus simplifying the use of a single palette with multiple ports and windows; System Software 6.0 and earlier require copies of the palette to use it with different windows.
Although this ability to associate one palette with multiple ports and windows will allow the use of calls like _PmForeColor and _PmBackColor, calling _ActivatePalette with an off-screen port does nothing, and as a result, calling it with an off-screen port will associate the palette with the port but will not cause any change in the color environment.
One important implication of this feature is that DisposeWindow (_DisposWindow) will not dispose of the associated palette automatically since it may be allocated to other ports or windows. The only exception to this behavior is when an application has used _GetNewCWindow to create the window, there is a 'pltt' resource with the same ID as the window, and the application has not called _GetPalette for the window.
Color Updates
System version 6.0.2 also introduces a new call, _NSetPalette, which complements _SetPalette. _NSetPalette has the same functionality as _SetPalette, but the CUpdates parameter has been modified from a Boolean to an Integer as follows:
_NSetPalette changes the palette associated with dstWindow to srcPalette. It also records whether the window wants to receive updates as a result of a change to its color environment. If you want dstWindow to be updated whenever its color environment changes, set nCUpdates to pmAllUpdates. If you are only interested in updates when dstWindow is the active window, set nCUpdates to pmFgUpdates. If you are only interested in updates when dstWindow is not the active window, set nCUpdates to pmBkUpdates.
_CopyPalette is a utility procedure that copies dstLength entries from the source palette into the destination palette; the copy begins at srcEntry and dstEntry, respectively. _CopyPalette will resize the destination palette when the number of entries after the copy is greater than the original.
_CopyPalette does not call _ActivatePalette, so the application is free to do a number of palette changes without causing a series of intermediate changes to the color environment; the application should call _ActivatePalette after completing all palette changes.
If either of the palette handles are NIL, _CopyPalette does nothing.
QD 10 - Picture Comments—The Real Deal
QuickDraw
Revised by: Joseph Maurer October 1992
Written by: Ginger Jernigan November 1986
Changes since March 1988: This Note (formerly titled “Optimizing for the LaserWriter—PicComments”) describes the picture comments defined and interpreted by the Apple printer drivers. Most of the picture comments are specific to PostScript, but we renamed the Note to emphasize that LaserWriter printers are not necessarily PostScript devices, and that QuickDraw printer drivers may implement their own picture comment handling. This Note has been completely rewritten and incorporates all additional insights gained during the last few years. We are also much more determined now to discourage the use of obsolete and problem-laden (although still supported) picture comments, and we carefully point out known problems or limitations of each comment.
Introduction
The QDProcs record (see Inside Macintosh Volume I, page 197) reflects the foundations of the architecture of QuickDraw. The commentProc field points to a procedure that processes picture comments, as included in a picture by means of the PicComment procedure (Inside Macintosh Volume I, page 189). This allows applications to include application-specific additional information in the pictures they create.
The QDProcs record also is the key to understanding how Macintosh printer drivers work. When the application calls PrOpenPage and draws into the printing grafPort, the printer driver collects the drawing commands by hooking into the QDProcs of the printing port. In particular, if an application calls the PicComment procedure while drawing into the printing grafPort, the printer driver gets a chance to capture and process the information contained in the kind and dataHandle parameters.
During the development of the original LaserWriter driver, it became obvious that applications should be able to take advantage of certain PostScript features that were not accessible through standard QuickDraw calls, such as rotated text and graphics, dashed lines, fractional line widths, and smoothed polygons. Also, certain applications needed a way to transmit their own native PostScript instructions to the printer. Picture comments seemed to be the ideal vehicle for providing these capabilities.
Unfortunately, there are conflicts with the device-independent nature of the Macintosh Printing Manager architecture. In this Note, we still want to document picture comments as completely and correctly as possible; and we want to tell you how to use the best of their features, while maintaining the important goal of device-independent printing and all- purpose PICTs. (This is why it has such a painful history!)
First, we give an overview of the picture comments as currently implemented by Apple’s printer drivers. This leads us immediately to the problem section “Cohabitation of QuickDraw and PostScript,” which also shows how to keep the QuickDraw and PostScript graphics states synchronized during printing. Finally, we discuss all the picture comments by subject, in the order suggested by Table 1.
Picture Comments Repertoire
The following picture comments are recognized by all PostScript LaserWriter drivers version 3.1 and later.
Table 1 PostScript LaserWriter Picture Comments
Data
Type Kind Size Data Description
TextBegin 150 6 TTxtPicRec Begin text function
TextEnd 151 0 NIL End text function
StringBegin 152 0 NIL Begin string delimitation
StringEnd 153 0 NIL End string delimitation TextCenter 154 8 TTxtCenter Offset to center of rotation
LineLayoutOff 155 0 NIL Turn LaserWriter line layout off
LineLayoutOn 156 0 NIL Turn LaserWriter line layout on
# ClientLineLayout 157 16 TClientLL Customize line layout error
distribution
PolyBegin 160 0 NIL Begin special polygon
PolyEnd 161 0 NIL End special polygon
PolyIgnore 163 0 NIL Ignore following polygon data
PolySmooth 164 1 PolyVerb Close, Fill, Frame
PolyClose 165 0 NIL Close the polygon
DashedLine 180 - TDashedLine Draw following lines as dashed
DashedStop 181 0 NIL End dashed lines
SetLineWidth 182 4 Point Set fractional line widths
PostScriptBegin 190 0 NIL Set driver state to PostScript
PostScriptEnd 191 0 NIL Restore QuickDraw state
PostScriptHandle 192 - PSData PostScript data in handle
† PostScriptFile 193 - FileName FileName in data handle
† TextIsPostScript 194 0 NIL QuickDraw text is sent as PostScript
† ResourcePS 195 8 Type/ID/Index PostScript data in a resource file
PSBeginNoSave 196 0 NIL Set driver state to PostScript
RotateCenter 202 8 Center Offset to center of rotation
# FormsPrinting 210 0 NIL Don’t clear print buffer after each page
# EndFormsPrinting 211 0 NIL End forms printing after PrClosePage
______________________________________
† These comments are obsolete.
# These comments are not recommended.
Most of the comments in Table 1 were designed specifically for the original LaserWriter driver. In fact, the term LaserWriter has been (and often still is) used in the sense of “PostScript printer,” and the LaserWriter driver is known to be basically a QuickDraw-to-PostScript translator. Meanwhile, however, QuickDraw-based LaserWriter models came out, so we should start being more careful in our terminology. This is why we insist on talking about PostScript drivers or PostScript printers when a picture comment applies to PostScript.
QuickDraw printer drivers may implement their own picture comments, or some of the above comments, in order to provide additional capabilities. Certain third-party printer drivers implement text rotation, for example, by supporting the TextBegin/TextCenter/ TextEnd picture comments.
Apple’s QuickDraw printer driver for the LaserWriter SC supports the following three picture comments:
LineLayoutOff 155 0 NIL Turn LaserWriter line layout off
LineLayoutOn 156 0 NIL Turn LaserWriter line layout on
SetLineWidth 182 4 Point Set fractional line widths.
The ImageWriter LQ driver and the first versions of the StyleWriter driver (prior to 7.2) implement the LineLayoutOff and LineLayoutOn picture comments. Even the ImageWriter driver reacts to picture comments:
BitMapThinningOff 1000 0 NIL Turn off hi-res bitmap thinning
BitMapThinningOn 1001 0 NIL Turn on hi-res bitmap thinning
The ImageWriter driver does the same toggling of the “bitmap thinning” of fat bitmaps in Best mode, when it encounters a TextBegin or TextEnd comment (undocumented feature—never mind!). The ImageWriter LQ driver handles these comments similarly.
The current StyleWriter driver (version 7.2.2) and the personal LaserWriter LS driver do not support any picture comments at all.
The point of all this is:
It is impossible to determine which picture comments
are supported by which printer driver.
In other words, your application should never assume a particular picture comment is available, but your application also should not defeat the device-independent design of the Macintosh printing architecture by writing printer driver–specific code!
Of course, you know (Inside Macintosh Volume II, page 152) that the high byte of the prStl .wDev field of the print record identifies a printer driver species, and that a value of $03 tells you the printer driver belongs to the PostScript LaserWriter driver ancestry. As a matter of fact, many applications use this information to achieve special printing features not available through the Printing Manager interface.
And, of course, you also know that we don’t like this idea. One reason is future system software may allow spool files to be redirected to a printer other than the one chosen when you sent your printing instructions (including picture comments). Another reason is that picture comments usually are included in PICTs; documents containing such pictures should print with optimal results on any printer configuration. And, finally, you never know what the future holds for you, in terms of new printing devices or new printer drivers—or a new printing architecture!
Instead, if a picture (i.e., a sequence of imaging instructions) contains picture comments to enhance the output on devices that support them, it should also contain a standard QuickDraw representation as a fallback solution, in case the rendering device does not recognize the picture comments. The design and implementation of these picture comments should incorporate conventions to make this cohabitation of two representations in one picture possible.
Cohabitation of QuickDraw and PostScript
Device-Independent Pictures
We can think of the Printing Manager’s PrOpenPage and PrClosePage calls as being analogous to the OpenPicture and ClosePicture calls (which, by the way, reminds us to never call OpenPicture between PrOpenPage and PrClosePage; see Inside Macintosh Volume II, page 160). In both cases, a stream of imaging instructions is recorded for deferred rendering. We want to create pictures that include both QuickDraw and optimized PostScript representations so that we obtain the best results in all circumstances. We must take special care for third-party QuickDraw printer drivers that support picture comments originally intended for PostScript devices only.
Let’s start with the easy ones.
The two picture comments PostScriptBegin and PostScriptEnd clearly suggest that any imaging instructions in between are intended exclusively for PostScript printing devices. In the case of the PostScript LaserWriter driver, the effect of PostScriptBegin is to disable all bottlenecks except commentProc, txMeasProc, getPicProc, and putPicProc. This means that QuickDraw’s text, line, shape (Rects, RoundRects, Ovals, Arcs, Polygons) and bitmap drawing calls don’t have any effect in the printing grafPort when enclosed by PostScriptBegin and PostScriptEnd. Instead, the PostScript LaserWriter driver expects to receive the imaging instructions as data enclosed in the PostScriptHandle comment. This way, both the PostScript and QuickDraw representation can coexist in the same picture without conflict. As a consequence, non-PostScript printer drivers, unable to interpret general PostScript text, must not imitate this behavior of ignoring QuickDraw instructions, even when they implement other picture comments such as TextBegin and TextEnd for text rotation. Otherwise, they would miss the QuickDraw representation of some PostScript imaging.
The text rotation picture comments (TextBegin, TextCenter, TextEnd) silently include the assumption that a printer driver that supports these comments
a. ignores the QuickDraw clipping region between TextBegin and TextEnd
b. ignores the QuickDraw CopyBits instruction within TextBegin/TextEnd
This way, a bitmap representation of the rotated text can be included in the picture. It will be used only if the TextBegin/TextEnd comments are not supported. Conversely, the QuickDraw commands required to draw the text to be rotated by the printer driver are “hidden” from QuickDraw by setting the clipping region to empty, which is ignored by the driver supporting the comments.
The polygon picture comments provide another solution to the problem, in form of the special comment PolyIgnore. It allows one to include a QuickDraw representation of the smoothed polygon, ignored by a driver that supports polygon smoothing (such as via PostScript’s curve operator). And for filled polygons, QuickDraw’s region concept works around a conflict of who owns which polygon (see sample code later in this Note).
Some picture comments (such as the line layout comments) do not require a fallback solution in case they are not supported by a printer driver; or the feature, if absent, is not a big loss (such as SetLineWidth, provided you use it only for widths smaller than one 72-dot-per-inch (dpi) QuickDraw pixel).
But for the picture comments DashedLine/DashedStop and RotateBegin/ RotateCenter/RotateEnd, there is no general solution to the “cohabitation” problem; and we are distressed about it. It is obvious that they have been defined with the PostScript LaserWriter driver in mind, without anticipating a future furnished by some 150 third-party printer drivers. The only way to include both representations in these cases is indeed to assume that only PostScript drivers will support the picture comment, such that the PostScriptBegin and PostScriptEnd comments can be used to “comment out” the QuickDraw representation.
Even under the above assumption, we still need a trick to prevent the QuickDraw calls within the scope of the picture comments from showing up when the comments are not recognized. Fortunately, early Macintosh developers discovered a QuickDraw feature that, unintentionally, solves the problem. Passing the “magic” mode 23 to PenMode inhibits QuickDraw’s normal drawing, but still lets the LaserWriter driver see the drawing instructions come through the bottlenecks, so that it can translate them into PostScript. Note that this pen mode always has been undocumented, and that using it was considered a compatibility risk and frowned upon for some time. Given the current state of affairs, however, there is no reason anymore to be paranoid about it.
Keeping QuickDraw and PostScript Synchronized
There are two situations, in the context of picture comments, where the design of the PostScript LaserWriter driver requires special precautions from the application programmer.
First, certain QuickDraw instructions like Move, MoveTo, PenPat, and PenSize change the state of the grafPort, without going through the QDProcs bottleneck procedures. A Macin-tosh printer driver takes these changes into account only at the time it executes an actual drawing instruction. Remember, the printer driver hooks into the QDProcs to get execution time and only “sees” instructions coming through the QDProcs. Nothing is wrong with it—unless PostScript code is woven into the graphics instructions by means of picture comments. (Note that PostScript code may be generated transparently when the LaserWriter driver encounters certain picture comments.) If the PostScript code assumes that the current state of the grafPort corresponds to what you expect it to be, then you have to flush the state of the grafPort explicitly before inserting the PostScript code. This is easier than it sounds; just do something inoffensive that goes through the QDProcs.lineProc bottleneck, like in the following utility procedure:
PROCEDURE FlushGrafPortState;
{ This routine causes the state of the Printing Manager's grafPort to be }
{ flushed out to the LaserWriter, by making a dummy call through the }
{ QDProcs.lineProc bottleneck. Pen size and pen location are preserved. }
Another unwanted effect is related to the PostScript LaserWriter driver’s multiple internal buffering of generated PostScript code. The PostScript code generated for text drawing instructions (which usually involves font queries and, sometimes, font downloading) is buffered independently from the PostScript code inserted by means of picture comments. In certain cases, this results in apparently nonsequential execution of drawing instructions, and may affect clipping regions or may have side effects on the PostScript code you included in picture comments. In order to synchronize the sequence of QuickDraw instructions with the generation of PostScript code, you need to call the following procedure:
PROCEDURE FlushPostScriptState;
{ This routine flushes the buffer maintained by the LaserWriter driver. }
{ All PostScript, generated either by the app or by the LaserWriter }
{ driver, will be sent to the device. }
BEGIN
PicComment(PostScriptBegin, 0, NIL);
PicComment(PostScriptEnd, 0, NIL);
END;
In the following discussion of picture comments, we’ll refer to these two utility routines as appropriate.
Text Rotation
Comments: TextBegin, TextCenter, TextEnd
These comments give access to PostScript’s capabilities of rotating, flipping, and justifying text. They are intended for applications likely to be used with PostScript printers (such as desktop publishing and advanced drawing applications), but which don’t want to use PostScript explicitly. Note that some non-PostScript printer drivers support these comments as well. For situations where the comments are not supported (such as the QuickDraw screen, or most QuickDraw printer drivers), you must provide a bitmap represen-tation of the rotated text as an alternative.
Let’s look at sample code right away.
USES PicComments; { See Appendix; defines constants for just and flip and }
{ the structures referred to by TTxtPicHdl and TCenterHdl.}
PROCEDURE QDStringRotation(s: Str255; ctr: Point;
just, flip: Integer; rot: Fixed); EXTERNAL;
{ This routine should generate a bitmap of the rotated and flipped text }
{ and use CopyBits to draw it to the grafPort. Left as an exercise ... }
{ PostScript graphics state now has rotated/flipped coordinates. }
oldClip := NewRgn;
GetClip(oldClip);
SetRect(zeroRect,0,0,0,0);
ClipRect(zeroRect); { Hides the following DrawString from QuickDraw }
DrawString(s); { in the rotated PostScript environment. }
ClipRect(oldClip^^.rgnBBox);
{ Now the "fallback" bitmap representation; see the comments above }
{ at the declaration of the QDStringRotation procedure. }
QDStringRotation(s, ctr, just, flip, rot);
PicComment(TextEnd,0,NIL); { Set environment back to the original state }
DisposHandle(Handle(hT));
DisposHandle(Handle(hC));
MoveTo(pt.h,pt.v); { to preserve the pen position }
END;
The preceding discussion about including both QuickDraw and PostScript representations and the comments included in the source code say it all: The conventions tied to the usage of the TextBegin and TextEnd picture comments allow you to take advantage of a printer driver’s implementation of high-resolution text rotation, while including a bitmapped representation for where the comments are not supported.
Some Additional Hints
• Because of QuickDraw’s orientation of the vertical coordinate axis, the rotation angle is measured clockwise. Nothing prevents us from using the negative angle if we are used to the counterclockwise orientation.
• The angle is measured in degrees (0..360), and passed as a Fixed type number (that is, if taken as a LongInt value, you have to divide it by 65536 to obtain the angle in degrees). For integer angles, it is possible to use a reduced TTxtPicRec structure that does not contain the tRotFrac field. The PostScript LaserWriter driver uses GetHandleSize(hT) to determine whether it must use the fractional angle in the tRotFrac field. To be safe, always set the tRot field to FixRound(tRotFrac) if you go with the extended TTxtPicRec (as we do here).
• It is convenient that clipping regions are ignored between the TextBegin and TextEnd picture comments, because it allows us to clip out the DrawString on printers that don’t support these comments. Unfortunately, this also means that text rotated this way can’t be clipped. If clipping of rotated text is required, you’ll have to do it entirely within PostScript.
• Due to the LaserWriter driver’s internal buffering of generated PostScript code, the effect of ignoring clip regions may be propagated to preceding sections of your drawing instructions. We recommend calling the FlushPostScriptState procedure described earlier immediately before the TextBegin comment.
• The tJus field in the TTxtPicRec, if different from tJusNone, tells the printer driver to maintain either the left, right, or center point of the string without recalculating the interword and intercharacter spacing. The tJusFull value specifies that the original length of the string (on the QuickDraw screen) must be maintained. This is important when the printer font has widths different from those of the screen font, and when you rotate justified blocks of text.
• The tFlip field in the TTxtPicRec specifies horizontal or vertical flipping about the center point specified by the TextCenter comment.
• The TextCenter comment specifies the center of rotation for any text enclosed within the TextBegin and TextEnd calls, as an offset to the location of the current point. The rotation is achieved by changing PostScript’s coordinate system. A sequence of DrawString – MoveTo instructions is rotated as a whole until TextEnd is encountered.
• Some versions of double-byte Kanji systems print Kanji characters by calling CopyBits instead of calling standard text drawing routines. This means the comments in the Text Rotation family cannot be used with these fonts. Instead, use the Graphics Rotation comment family described later in this Note.
When drawing to a printing grafPort, the selected printer driver does a lot of work “behind the scenes” to try to maintain the infamous “What-You-See-Is-What-You-Get” (WYSIWYG) metaphor from the screen to the paper, and generally to make the printed output look as good as possible. Depending on the target device, the printer driver, and the configuration of fonts in the system, the font you draw text with may be scaled, smoothed, remapped, or even replaced by a font built into the printer. In nearly all cases where the device resolution of the printer is different from QuickDraw’s “hard-coded” 72-dpi screen resolution, the width of text rendered on the printer is different from the text width on the screen. This is due to nonproportionally scaling bitmapped fonts, different character widths after font substitution, and rounding errors of fractional character widths on the screen. The difference in the width of a line of text is called the line layout error.
The printer driver is responsible for adjusting the word and character spacing in the printed output so that the two widths are identical. If it doesn’t, apparently fully justified text on the screen may appear ragged on the paper, and certain lines of text may extend beyond the right border and be badly clipped. Many existing applications make this task really difficult for the printer drivers (don’t blame them, though!). They position the words (or even characters) separately on a line, and the printer driver has to figure out how to collect the complete line before applying its line layout algorithm to distribute the difference of the text widths into word and character spacing. Given the uneven distribution of the character width differences, and the requirement of achieving good typographical quality in the printed output, it is unavoidable that the position and width of a word within a justified line differs slightly from what appears on the screen; only the length of the whole line is maintained.
In computing the required line layout adjustments, the LaserWriter driver proceeds as follows:
1. It collects text coming through the printing grafPort’s textProc bottleneck, and heuristically puts it together into what it “believes” is a logically contiguous line of text. This includes text moved vertically away from the baseline, to take care of indices or exponents in the text. The process of accumulating text is stopped when the LaserWriter driver detects that the horizontal component of the pen position has changed since the previous text drawing instruction, or when picture comments like TextBegin, TextEnd, StringBegin, StringEnd are encountered.
2. It determines the width of the accumulated logical line of text, both on the screen and on the printer, and distributes the line layout error among the interword and intercharacter spacing of the printed output.
The LineLayoutOff picture comment disables only the second step (distribution of the line layout error); the heuristic algorithm of accumulating text into a logically contiguous piece is not affected. Otherwise, if the character widths of the printer font are different from those of the screen font, and if the text contains exponents or indices, the latter would often be misplaced.
The following code fragment shows a probably unexpected consequence of this behavior. We draw a line in two pieces three times. A vertical line shows the starting pen position of the second DrawString call. The second line is enclosed by LineLayoutOff and LineLayoutOn picture comments.
PROCEDURE ObserveLineLayout;
CONST
testString1 = 'Whatever you like, preferably ';
testString2 = 'with spaces, long and short words';
fontName = 'New York';
fontSize = 14;
x0 = 20; { starting point }
y0 = 40;
h = 30; { line height }
VAR
familyID: Integer;
w, y : Integer;
BEGIN
GetFNum(fontName, familyID);
TextFont(familyID);
TextSize(fontSize);
w := StringWidth(testString1);
y := y0;
MoveTo(x0 + w, y - h);
Line(0, 4 * h); { This is to estimate the difference. }
{ Draw the first line, in two pieces. }
{ This is the default line layout behavior of the LaserWriter driver. }
MoveTo(x0, y);
DrawString(testString1);
MoveTo(x0 + w, y);
DrawString(testString2);
{ Draw the second line, in the same way as above. }
{ Because of the LineLayoutOff picture comment, the unmodified widths }
{ of the printer font are used. }
y := y + h;
PicComment(LineLayoutOff, 0, NIL);
{ ••• (1) •••}
MoveTo(x0, y);
DrawString(testString1);
MoveTo(x0 + w, y);
{ ••• (2) •••}
DrawString(testString2);
y := y + h;
PicComment(LineLayoutOn, 0, NIL);
{ Back to the original behavior. }
MoveTo(x0, y);
DrawString(testString1);
MoveTo(x0 + w, y);
DrawString(testString2);
END;
And this is (approximately) the output of the ObserveLineLayout (with LaserWriter driver version 7.1.1, and the default setting “Font Substitution enabled”):
Figure 1—Effect of the LineLayoutOff comment
For most noticeable effects, we choose the bitmapped New York font, such that the LaserWriter driver substitutes PostScript Times (note that there are no line layout problems with TrueType fonts, unless the TrueType font has the same name and different cha-rac-ter widths as a printer-resident PostScript font). The screen font New York is larger than the PostScript font Times, and in the first and third lines, the printer driver (after accumulating testString1 and testString2 into one logical line) distributes the line layout error (mainly) among the spaces between words. You may even notice that the starting point of testString2 (“with ...”) has been slightly moved to the left in the process. The width of the whole line, however, is the same as on the screen.
The second line, where the LineLayoutOff comment is active, demonstrates a dramatic counterexample to the popular belief that this picture comment is here to assure precise positioning of text. It seems the opposite is true, and the LaserWriter driver has deliberately ignored the MoveTo(x0+w,y) instruction! What we would have expected is this:
Figure 2—Desired result of the LineLayoutOff comment
The attentive reader already knows the explanation. As mentioned earlier, we must break the LaserWriter driver’s heuristic line accumulation algorithm before drawing testString2. Short of adequate documentation, developers have found out that a FlushGrafPortState call right after the MoveTo(x0+w,y) instruction has the desired effect (see {••• (2) •••} in the code snippet given earlier). Unfortunately, it creates quite a lot of overhead in the pictures, and penalizes all printer drivers that don’t need it. A better solution is to use the StringBegin and StringEnd picture comments at the markers {••• (1) •••} and {••• (2) •••} in the code shown earlier. This indicates that testString1 is to be considered a logically independent text entity, and must not be put together with any other pieces of text coming through the textProc bottleneck. The overhead of these comments is much smaller, and they don’t affect other printer drivers at all.
The ClientLineLayout picture comment, supported by the (PostScript) LaserWriter driver, has never been documented. Its effect is rather subtle and very specific to the PostScript LaserWriter driver. Basically, it allows the application to redefine the character that absorbs the major part of the line layout error (usually the space character), and the percentages of the “major” and “minor” parts of the line layout error (usually 80 percent versus 20 percent). The “minor” part is distributed across intercharacter spacing.
Only very ambitious page layout applications might be interested in this functio-na-lity; but then, they should rather aim at a more general scheme of line layout control that does not rely upon this very driver-specific picture comment.
The PicComment.p interface (see the Appendix) describes the TClientLLRecord structure passed through the handle parameter to the picture comment. If you want, feel free to experiment with it; we recommend, however, that you do not use this picture comment in your application.
Caveats
• Some older printer drivers supporting the LineLayoutOff picture comment are unable to correctly obey a subsequent LineLayoutOn picture comment.
• Don’t forget that if you use LineLayoutOff, the burden of “WYSIWYG” is now on your shoulders, and not the printer driver’s.
• A previous version of this Note said that setting the Font Manager’s FractEnable global to TRUE implied the effect of the LineLayoutOff picture comment. As it turned out, the statement was based on observations with a specific (older) version of the LaserWriter driver, and is not true in general. The setting of FractEnable does have some more or less subtle effects on the line layout algorithm, however; and this is quite plausible. Similarly, the results of combining the picture comments LineLayoutOff and LineLayoutOn with calls to SpaceExtra (Inside Macintosh Volume I, page 172) or CharExtra (Inside Macintosh Volume V, page 77) are sometimes unpredictable, depending on the particular printer driver.
And Finally the Good News
Given that the effect of the LineLayoutOff and LineLayoutOn comments does not require any changes in your printing code, you don’t have to worry whether or not a particular driver supports them. They are useful mainly when you’re sure you want no external assistance in computing word and character spacing for full justification, or when you need precise control over the horizontal placement of words and characters (such as in forms or tabulated text) and understand how to achieve this.
String Delimitation
Comments: StringBegin, StringEnd
These comments allow applications to specify the logical beginning and end of a string, possibly drawn with multiple calls to a QuickDraw text drawing routine (such as DrawChar). If this was their only raison d’être, they would have no relationship with the PostScript LaserWriter driver. But, as already let out in the preceding section on line layout, they are important to notify the printer driver that it should consider the text coming through the textProc bottleneck between StringBegin and StringEnd as an independent entity. Otherwise, the driver might continue to perform its heuristic accumulation of text drawing instructions for the same line, and defeat your text positioning intentions. Indeed, both StringBegin and StringEnd trigger the generation of PostScript instructions for drawing the text that has been accumulated in a line layout buffer, and reinitialize the internal variables for line layout computations. In other words, you need these picture comments to turn the LaserWriter driver’s line layout behavior completely off.
PostScript has the built-in capability of drawing cubic Bézier curve sections (see the PostScript Language Reference Manual, Second Edition, page 393). This is convenient for “smoothing” of polygons. The polygon-related picture comments have been provided to give applications easy access to this PostScript feature, with provision for including a QuickDraw approximation of the curve.
Schematically, the polygon comments are used as follows:
PolyBeginComment; { Put the PostScript driver into “polygon mode.” }
ClipRect(zeroRect); { Hide the following from QuickDraw. }
PolyCloseComment; { Optionally, if “closed” smoothing desired. }
PolySmoothComment; { Tell the driver to draw a Bézier curve. }
DrawPolygon; { Invisible for QuickDraw; PostScript output = curve. }
PolyIgnoreComment; { The driver will ignore the following line drawing. }
SetClip(origClipRgn); { Make it visible for QuickDraw. }
DrawQDPolygon; { Usually, a QuickDraw approximation of the curve. }
PolyEndComment; { PostScript driver resumes standard mode. }
A piece of sample code is sometimes worth more than one or two pictures; below, you’ll find both. For clarity and completeness of the exposition, we provide the coordinate definition of the polygons through arrays of Points, initialized in a preliminary DefineVertices procedure. You can enclose the PolygonDemo procedure between OpenPicture and ClosePicture calls to create a picture containing both QuickDraw and PostScript representations (see Figures 3 and 4), or you can use it as is when a printing page is open.
USES PicComments;
{ See Appendix of this Note for the definition of the TPolyRec structure. }
CONST
kN = 4; { number of vertices for PostScript }
kM = 6; { number of vertices for QuickDraw approximation }
TYPE
PointArray = array[0..0] of Point; { range checking OFF }
PointArrayPtr = ^PointArray;
PROCEDURE DefineVertices(VAR p,q: PointArrayPtr);
CONST
cx = 280;
cy = 280;
r0 = 200;
BEGIN
{ The array p^ contains the control points for the Bézier curve: }
SetPt(p^[0],cx + r0,cy);
SetPt(p^[1],cx,cy + r0);
SetPt(p^[2],cx - r0,cy);
SetPt(p^[3],cx,cy - r0);
p^[4] := p^[0];
{ q^ contains the points for a crude polygon approximation of the curve: }
q^[0] := p^[0];
SetPt(q^[1],cx,cy + round(0.7 * (p^[1].v - cy)));
SetPt(q^[2],(p^[1].h + p^[2].h) DIV 2,(p^[1].v + p^[2].v) DIV 2);
SetPt(q^[3],cx + round(0.8 * (p^[2].h - cx)),cy);
SetPt(q^[4],q^[2].h,cy + cy - q^[2].v);
SetPt(q^[5],q^[1].h,cy + cy - q^[1].v);
q^[6] := q^[0];
END;
PROCEDURE PolygonDemo;
VAR
p,q: PointArrayPtr;
aPolyVerbH: TPolyVerbHdl;
i: Integer;
clipRgn, polyRgn: RgnHandle;
zeroRect: Rect;
BEGIN
p := PointArrayPtr(NewPtr(SizeOf(Point) * (kN + 1)));
1. The fPolyFrame and fPolyFill fields of the TPolyRec record are self-explanatory. The fPolyClose flag is redundant with the PolyClose picture comment, but is included for the convenience of the LaserWriter driver. It is often misunderstood. It does not mean the polygon is being closed automatically, such as with the PostScript closepath operator; instead, it affects the shape of the smooth curve. Figure 4 shows the result for fPolyClose = FALSE; the start and end point of the polygon is distinguished. In the case of fPolyClose = TRUE, all vertices of the polygon are treated in the same manner, and the resulting curve resembles a circle (in this case).
2. The anonymous fields f3..f7 are reserved and should be set to zero (that is, FALSE).
3. The polygon is drawn at the current pen location when the PolyBegin comment is received.
4. In general (and in this example), you do not need to open a region, collect the line segments in the region, and draw the polygon through FrameRgn. It is demonstrated here only to prepare you for situations where you want to fill the polygon with a pattern. You cannot open a polygon and use FillPoly, because the PostScript driver “owns” the polygon concept at this point and captures—and ignores—all line drawing between the PolyIgnore and PolyEnd comment. Regions do not interfere with polygons, however, and can be used to paint or fill the polygonal shape.
Caveats
PostScript Level 1 has problems with very large polygons (more than about 1000 points). The workaround is to subdivide the large polygon into several smaller ones.
You cannot combine the polygon picture comments with other comments such as the rotation comments or the DashedLine comment. It’s just another limitation—no comment.
Dashed Lines
Comments: DashedLine, DashedStop
PostScript allows applications to draw precisely dashed lines with a given dash pattern in every direction (see the setdash operator, PostScript Language Reference Manual, Second Edition, page 500). The QuickDraw ersatz of setting the pen pattern appears to be awkward at best; the result depends very much on the direction of the line. Coding correctly dashed lines in QuickDraw is quite a hassle and rather clumsy. This is why the DashedLine and DashedStop picture comments have been provided for applications where dashed lines are important and used frequently. Applications can take advantage of these comments when printing to a PostScript printer.
The DashedLine comment tells the driver that the line drawing instructions following the comment should be dashed according to the parameters in the TDashedLine structure (see the Appendix). These parameters closely correspond to the parameters passed to the PostScript setdash operator. Only the centered field of the TDashedLine structure is not currently supported by the LaserWriter driver. It should be set to 0 in case support for centering is added in the future.
Unlike the picture comments for text rotation or even polygon smoothing, the DashedLine picture comment should not be supported by a non-PostScript driver. The only way to include representations of dashed lines with and without usage of the DashedLine picture comment is to make the following assumption: If the DashedLine comment is supported, then the printer is a PostScript printer, and the PostScriptBegin/PostScriptEnd bracket may be used to hide the QuickDraw imaging from the printer. Remember that non-PostScript printer drivers must not ignore QuickDraw imaging within PostScriptBegin and PostScriptEnd!
But we still need a trick to hide the line drawing instructions within the DashedLine – DashedStop bracket from QuickDraw. Here comes the “magic pen mode” to our rescue:
PROCEDURE DashDemo;
CONST
magicPen = 23; { the infamous penMode ! }
cx = 280;
cy = 280;
r0 = 200;
VAR
dashHdl: TDashedLineHdl;
i: Integer;
a, rad : Extended;
BEGIN
PenSize(2,2);
{ First the PostScript picture comment version. }
{ The "magic pen mode" 23 makes the line drawing invisible for QuickDraw. }
{ Now, the QuickDraw version. The PostScript driver must ignore it, }
{ so we enclose it between PostScriptBegin and PostScriptEnd comments.}
PicComment(PostScriptBegin, 0, NIL);
PenSize(2,2);
FOR i := 0 TO 9 DO BEGIN
MoveTo(cx,cy);
DashedQDLine(round(r0 * cos(i * 20 * rad)),
- round(r0 * sin(i * 20 * rad)), dashHdl);
END;
PicComment(PostScriptEnd,0,NIL);
END;
By the way: The DashedQDLine procedure is intentionally missing. It’s not precisely the subject of this Note, and thus, again, is left as a spare-time exercise for the reader.
Caveat
As mentioned earlier, the current version of the PostScript LaserWriter driver produces poor results when the DashedLine picture comment is applied to polygons. Just don’t do it!
Fractional Line Width
Comment: SetLineWidth
QuickDraw’s design is based on a fixed 72-dpi resolution. Even when printing to a high-resolution device, the Printing Manager presents the printing grafPort, corresponding to the printable area of the page, in the integer-valued QuickDraw coordinate system with 72 dpi. Applications can use PrGeneral to image at higher device resolutions (see Inside Macintosh Volume V, page 410), but this is useful mainly for immediate printing. As a consequence, lines are usually always at least 1/72 inch wide, corresponding to the smallest pen size (1,1). For a 300-dpi device like the LaserWriter, this is disappointing.
The SetLineWidth comment allows an application to set the width of a line to any fractional value. A value of 1/4 approximately corresponds to a “hairline” on a 300 dpi LaserWriter. Curiously (but conveniently), a QuickDraw Point structure is passed in the PicComment’s data handle, the vertical coordinate representing the denominator, and the horizontal coordinate the numerator of the fraction.
Unfortunately, it is not implemented in all high-resolution QuickDraw printers; and if it is (as in the LaserWriter SC), it works differently than in PostScript printer drivers. Moreover, there is no possibility to include alternative imaging instructions in case SetLineWidth is not supported. While this is not much of a loss for hairlines, it prevents us from using the comment for fractional widths > 1, where the alternative would be to include a PenSize call with rounded arguments. Another drawback may be that, allegedly, there are plotter drivers out there that abuse this comment to set the pen color—clearly an unpleasant situation.
The difference in the implementation of the SetLineWidth comment between the PostScript LaserWriter driver and the LaserWriter SC appears as soon as SetLineWidth is used for the second time. The PostScript driver keeps an internal line scaling factor; this factor is initialized to 1.0 when a job is started. Each number passed through SetLineWidth is multiplied by the current internal scaling factor to get the effective scaling factor for the pen size. The LaserWriter SC driver, on the other hand, replaces its current scaling factor for the pen size completely by the new value passed through SetLineWidth. In order to support both implementations, you must always use an additional SetLineWidth step in order to reset the PostScript driver line width to 1.0, before scaling to the new value.
Example
Let’s say you have set the line width to 0.25, and want to replace it by a line width of 0.5. The following two SetLineWidth comments will have the desired effect on both PostScript (PS) and QuickDraw (QD) drivers that implement the SetLineWidth comment. You don’t care about the temporary line width of 4.0 on the QuickDraw driver.
Current Line Width Parameter Passed New Line Width
PS driver QD driver in SetLineWidth PS Driver QD Driver
0.25 0.25 4/1 1.0 4.0
1.0 4.0 1/2 0.5 0.5
The following sample code gives the expected results only on a PostScript LaserWriter and on QuickDraw printer drivers that have the SetLineWidth comment implemented.
oldWidth,newWidth: TLineWidth; { actually a "Point" }
i,j,y: Integer;
BEGIN
PenNormal;
y := y0;
SetPt(oldWidth,1,1); { initial linewidth = 1.0 }
FOR i := 1 TO 5 DO BEGIN
SetPt(newWidth,4,i);
{ want to set it to i/4 = 0.25, 0.50, 0.75 ... }
SetNewLineWidth(oldWidth,newWidth);
MoveTo(x0, y);
Line(d0, 0);
y := y + e0;
oldWidth := newWidth;
END;
END;
•A Slight Imperfection
•
•If you experiment with the above code and draw a whole series of hairlines, you will see (depending on the values of e0 and kN) that certain lines appear thicker than they should be. This is due to rasterization effects in PostScript’s scan conversion algorithm when the line width is close to the device pixel size. In many cases, the PostScript LaserWriter driver tries to compensate for this by rounding coordinates to the 300-dpi grid. If you include SetLineWidth (or, by the way, DashedLine) picture comments, however, this does not work. PostScript Level 2 addresses this problem by means of an optional stroke adjustment feature (see the PostScript Language Reference Manual, Second Edition, pages 322 and 515).
Graphics Rotation
Comments: RotateBegin, RotateCenter, RotateEnd
Like the picture comments discussed earlier in this Note in the section “Text Rotation,” the graphics rotation picture comments provide a method of rotating QuickDraw objects on PostScript devices. Instead of having QuickDraw perform the rotation, the printer driver rotates the entire PostScript coordinate space so that everything drawn between RotateBegin and RotateEnd will be rotated on the printer itself. This includes text drawing! You specify the center of rotation with RotateCenter and the angle of the rotation, together possibly with horizontal or vertical flipping, through the TRotation record (see the interface definitions in the Appendix).
Unlike text rotation, you must insert the RotateCenter comment and pass the relative offset to the center of rotation before you use the RotateBegin picture comment. The point passed to RotateCenter specifies the offset from the anchor point of the first object drawn after RotateBegin to the desired center of rotation. Once you set up the rotation parameters with RotateCenter and RotateBegin, you can draw the graphics objects you want to rotate.
Bad news: In order to include a QuickDraw representation of the rotated objects in case the rotation comments are not supported, we have to assume (again) that only PostScript drivers implement these comments. The only way to hide the QuickDraw substitute from the driver is to surround it by PostScriptBegin and PostScriptEnd comments; and, similarly to the DashedLine comment, we need to use the “magic pen mode” (23) to hide the unrotated drawing between RotateBegin and RotateEnd from QuickDraw. The following sample demonstrates this:
The PostScript comments tell the picture interpreter (usually the LaserWriter driver) that the application is going to communicate with the LaserWriter directly using PostScript code instead of QuickDraw. All QuickDraw drawing instructions between the PostScriptBegin and PostScriptEnd picture comments are ignored. The driver sends the PostScript text contained in the PostScriptHandle data to the printer with no preprocessing and no error checking. When the application is finished sending PostScript, the PostScriptEnd comment tells the printer driver to resume normal QuickDraw mode. The driver uses the PostScript save and restore operators to preserve the state of the PostScript interpreter across the section enclosed by PostScriptBegin and PostScriptEnd. Some applications do not want to restore the previous state of the PostScript interpreter after including their PostScript code; for these situations, the PSBeginNoSave comment is a replacement for PostScriptBegin that does not preserve the state. Clearly, this comment should be used with extreme caution.
Some state information may be stored in global variables, so nesting PostScriptBegin (or PSBeginNoSave) and PostScriptEnd comments is not allowed.
The PostScriptHandle comment gives developers direct access to PostScript from applications. Instead of having the LaserWriter driver convert QuickDraw calls into the corresponding PostScript code, the application can generate its own PostScript, and transmit it to the printer or include it in a picture through the data handle of the PicComment procedure. The handle contains pure ASCII text; the valid length of the data is specified in the PicComment’s size parameter. Don’t forget to terminate the PostScript text at least with a space character, or better with a carriage return (ASCII $0D), so that it is separated from the following PostScript instructions (either yours, or the printer driver’s).
You must still use PostScriptBegin (or PSBeginNoSave) and PostScriptEnd around PostScriptHandle comments or the LaserWriter driver will not properly save and restore the PostScript drawing environment.
As with all picture comments, the handle you pass belongs to you and you must dispose of it when you’re finished with it.
PROCEDURE PostScriptLine(s: Str255);
{ A utility procedure to transmit a string of PostScript code through }
{ the PostScriptHandle picture comment to the PostScript printer. }
{ It should be called only between PostScriptBegin and PostScriptEnd }
{ picture comments. }
VAR
h: Handle;
BEGIN
h := NewHandle(256);
IF h = NIL THEN DebugStr('NewHandle failed');
BlockMove(@s[1],h^, Length(s));
PicComment(PostScriptHandle, Length(s), h);
h^^ := 13;
PicComment(PostScriptHandle, 1, h); { add a carriage return }
{ Let's test to see if the definition from above is still avail-}
{ able. This assumes that no font downloading has occurred. }
PicComment(PostScriptBegin,0,NIL);
PostScriptLine('//userdict /myFrameRect get exec ');
PicComment(PostScriptEnd,0,NIL);
END;
Caveat
If you choose to use PostScript directly in your pictures, be very careful not to make assumptions about Apple’s "md" dictionary (essentially the contents of the former LaserPrep file). Otherwise, your pictures will not print correctly with future versions of the PostScript LaserWriter driver. Also, be aware of compatibility problems within the PostScript world, and watch out for printers with PostScript Level 1 and PostScript Level 2 interpreters, and “PostScript-compatible” printers (PostScript clones).
FormsPrinting Picture Comments
Comments: FormsPrinting, EndFormsPrinting
The FormsPrinting comment tells the PostScript LaserWriter driver not to clear its page buffer after printing a page. EndFormsPrinting turns this mode off. When the page is completed, the application must erase the areas that need to be updated and draw the new information. The graphics that make up the form are drawn only once per page, which may improve performance. Currently, you need to write special printing code for the PostScript LaserWriter driver if you want to use this comment.
(More or Less) Obsolete PostScript Picture Comments
Comments: SetGrayLevel,
TextIsPostScript, ResourcePS, PostScriptFile
The SetGrayLevel picture comment was designed to provide access to the PostScript setgray operator while still drawing with QuickDraw in black-and-white mode. In practice, this turned out to be not so useful, however. For most drawing operations, the printer driver sets the gray level to match the foreground color currently stored in the printing grafPort, and the effect of the SetGrayLevel comment is often unpredictable. If direct access to the PostScript setgray operator seems nevertheless desirable, it is easy to include the instruction in a PostScriptHandle comment.
The TextIsPostScript picture comment takes all the text coming through standard QuickDraw text drawing calls (DrawChar, DrawString, DrawText, and anything else that eventually calls the StdText bottleneck), and interprets it as a PostScript program. There is no good reason to use this picture comment, but there is one important reason not to use it: Printer drivers that do not deal with the TextIsPostScript comment will print the PostScript text instead of interpreting it! If you need to transmit pure PostScript code directly to a printer that understands it, use the PostScriptHandle comment, and include a QuickDraw representation for all other printer drivers.
The ResourcePS picture comment loads PostScript code from a specified resource. The resource file is expected to be open at the time that the ResourcePS comment is used. Under background printing, there are no guarantees the file will still be open when the Printing Manager needs it. For this reason alone, you should forget about this comment. If you want to keep PostScript instructions in a resource, it is easy to write a small routine that loads the resources and sends their contents using the PostScriptHandle comment described earlier in this Note.
PostScriptFile has the same problems as ResourcePS described above. Basically, the Printing Manager cannot guarantee that the file will be available when it’s needed.
Appendix: Pascal Interface for Picture Comments
(File PicComments.p)
CONST
TextBegin = 150;
TextEnd = 151;
StringBegin = 152;
StringEnd = 153;
TextCenter = 154;
LineLayoutOff = 155;
LineLayoutOn = 156;
ClientLineLayout = 157;
PolyBegin = 160;
PolyEnd = 161;
PolyIgnore = 163;
PolySmooth = 164;
PolyClose = 165;
DashedLine = 180;
DashedStop = 181;
SetLineWidth = 182;
PostScriptBegin = 190;
PostScriptEnd = 191;
PostScriptHandle = 192;
PostScriptFile = 193;
TextIsPostScript = 194;
ResourcePS = 195;
PSBeginNoSave = 196;
SetGrayLevel = 197;
RotateBegin = 200;
RotateEnd = 201;
RotateCenter = 202;
FormsPrinting = 210;
EndFormsPrinting = 211;
tJusNone = 0; { values for the tJus field of the TTxtPicRec record }
tJusLeft = 1;
tJusCenter = 2;
tJusRight = 3;
tJusFull = 4;
tFlipNone = 0; { values for the tFlip field of the TTxtPicRec record }
tFlipHorizontal = 1;
tFlipVertical = 2;
TYPE
TTxtPicHdl = ^TTxtPicPtr;
TTxtPicPtr = ^TTxtPicRec;
TTxtPicRec = PACKED RECORD
tJus : Byte;
tFlip : Byte;
tAngle: Integer; { clockwise rotation in degrees 0..360 }
tLine : Byte; { Unused/Ignored }
tCmnt : Byte; { reserved }
tAngleFixed: Fixed; { same as "tAngle" in Fixed precision }
END; { TTxtPicRec }
TRotationHdl = ^TRotationPtr;
TRotationPtr = ^TRotation;
TRotationRec = RECORD
rFlip: Integer;
rAngle: Integer; { clockwise rotation in degrees 0..360 }
rAngleFixed: Fixed; { same as "rAngle" in Fixed precision }
END; { TRotationRec }
TCenterHdl = ^TCenterPtr;
TCenterPtr = ^TCenter;
TCenterRec = RECORD {offset from current pen location to center of rotation}
y: Fixed;
x: Fixed;
END; { TCenterRec }
TPolyVerbHdl = ^TPolyVerbPtr;
TPolyVerbPtr = ^TPolyVerbRec;
TPolyVerbRec = PACKED RECORD
f7,f6,f5,f4, f3, { reserved }
fPolyClose, { TRUE = smoothing across endpoint.}
fPolyFill, { TRUE = Polygon should be filled. }
fPolyFrame: BOOLEAN; { TRUE = Polygon should be framed. }
END;
TDashedLineHdl = ^TDashedLinePtr;
TDashedLinePtr = ^TDashedLineRec;
TDashedLineRec = PACKED RECORD
offset : SignedByte; { offset into pattern for } { first dash }
centered : SignedByte; { (Ignored) }
intervals: ARRAY [0..5] { Array of dash intervals }
OF SignedByte; { intervals[0] = number }
END; { of interval specs. }
TLineWidthHdl = ^TLineWidthPtr;
TLineWidthPtr = ^TLineWidth;
TLineWidth = Point; { v = numerator, h = denominator. }
TClientLLHdl = ^TClientLLPtr; { used in the ClientLineLayout picture comment }
TClientLLPtr = ^TClientLLRec;
TClientLLRec = RECORD
chCount : Integer; { Apply for so many characters. }
major : Fixed; { percentage of line layout error to be }
{ distributed among space characters. }
spcChar : Integer; { code of character that is to absorb }
{ the "major" line layout error }
minor : Fixed; { percentage of intercharacter distrib. }
ulLength: Fixed; { underline length. }
END;
Further Reference:
• PostScript Language Reference Manual, Adobe Systems Inc.
• Inside Macintosh, Volumes II, V, and VI
• LaserWriter Reference Manual, Addison-Wesley
• Macintosh Technical Note M.IM.AppPictComments —
Every Picture [Comment] Tells Its Story, Don’t It?
• Macintosh Technical Note M.IM.PictAndPrinting —
Pictures and the Printing Manager
• develop Issue 3, “Meet PrGeneral” by Pete “Luke” Alexander
Adobe is a trademark of Adobe Systems Incorporated.
PostScript is a registered trademark of Adobe Systems Incorporated.
QD 11 - Pictures and Clip Regions
QuickDraw
Revised by: March 1988
Written by: Jennifer Jernigan January 1986
This note describes a problem that affects creation of QuickDraw pictures.
When a GrafPort is created, the fields in the GrafPort are given default values; one of these is the clip region, which is set to the rectangle (–32767, –32767, 32767, 32767). If you create a picture, then call DrawPicture with a destination rectangle that is not the same size as the picFrame without ever changing the default clip region, nothing will be drawn.
When the picture frame is compared with the destination rectangle and the picture is scaled, the clip region is scaled too. In the process of scaling, the clip region you end up overflows and becomes empty, and your picture doesn’t get drawn. If you call ClipRect(thePort^.portRect) before you record the picture, the picture will be drawn correctly. The clipping on the destination port when playing back the picture is irrelevant: once a picture is incorrectly recorded, it is too late.
Further Reference:
• QuickDraw
QD 12 - Plotting Small Icons
QuickDraw
Revised by: James Beninghaus October 1989
Written by: James Beninghaus & Dennis Hescox August 1989
This Technical Note discusses the 'SICN' resource format and how to plot one in a GrafPort.
Changes since August 1989: Corrected errors in the Pascal code and spruced up the rest.
Introduction
Apple first introduced the 'SICN' resource so that the Script Manager could represent which country specific resources are installed in the system by displaying a small icon in the upper right corner of the menu bar. You can pass a 'SICN' resource to the Notification Manager or Menu Manager, and they will draw it for you automatically—you should continue to let them do so. However, if you want to draw a small icon in your application’s window, then this Note can help.
What does a 'SICN' look like? Following is a 'SICN' representation of a dogcow to help answer this question:
SICN' FatBits
There is reason to believe that this representation is actually a baby dogcow. Due to the protective nature of parent dogcows, young dogcows are rarely seen. This one was spotted during a DTS meeting after it drew attention to itself by crying “moo! woof!”. (Note that this dogcow said “moo! woof!” because it was immature; adult dogcows naturally say, “Moof!”.)
'SICN' Resource
A 'SICN' resource contains any number of small icon bit images. Each small icon in a 'SICN' list describes a 16 by 16 pixel image and requires 32 bytes of storage. Like an 'ICN#' resource, there is no count of the number of icons stored in a 'SICN'. The following 'SICN' resource, in MPW Rez format, contains two small icons:
The Macintosh Toolbox interfaces do not describe all the necessary data structures needed to work with 'SICN' resources. As shown in the following example, defining the 'SICN' type as an array of 16 short integers and the handles and pointers to this array type make life much easier.
Pascal
TYPE
SICN = ARRAY[0 .. 15] of INTEGER;
SICNList = ARRAY[0 .. 0] of SICN;
SICNPtr = ^SICNList;
SICNHand = ^SICNPtr;
C
typedef short SICN[16];
typedef SICN *SICNList;
typedef SICNList *SICNHand;
The Missing Count
The 'SICN' resource does not provide a count to indicate the number of small icons contained within; however, you can easily determine this number by dividing the total size of the resource by the size of a single small icon.
Pascal
CONST
mySICN = 1984;
VAR
theSICN : SICNHand;
theSize : LONGINT;
theCount : LONGINT;
theIndex : LONGINT;
theSICN := SICNHand(GetResource('SICN', mySICN));
IF (theSICN <> NIL) THEN BEGIN
theSize := GetHandleSize(Handle(theSICN));
theCount := theSize DIV sizeof(SICN);
END;
C
#define mySICN 1984
SICNHand theSICN;
long theSize;
long theCount;
long theIndex;
theSICN = (SICNHand) GetResource('SICN', mySICN);
if (theSICN) {
theSize = GetHandleSize((Handle)theSICN);
theCount = theSize / sizeof(SICN);
}
The Plot 'SICN's
The example procedure PlotSICN draws one small icon of a 'SICN' resource. It takes the handle from theSICN and the position in the list from theIndex within the rectangle theRect of the current GrafPort.
Following is an example call to PlotSICN which plots all the small icons in a resource into the same rectangle:
Pascal
SetRect(theRect, 0, 0, 16, 16);
FOR theIndex := 0 TO theCount-1 DO
PlotSICN(theRect, theSICN, theIndex);
C
SetRect(&theRect, 0, 0, 16, 16);
for (theIndex = 0; theIndex < theCount ; ++theIndex)
PlotSICN(&theRect, theSICN, theIndex);
Because PlotSICN uses _CopyBits and _CopyBits can move memory, you should lock the handle to the 'SICN' once the resource is loaded. Notice that the PlotSICN procedure dereferences the 'SICN' handle, adds an offset, and copies the resulting value. If the 'SICN' list moves in memory at this time, the bitmap’s baseAddr is useless.
To play it safe, PlotSICN saves a copy of the master pointer flags associated with the relocatable block, locks the block with a call to _HLock, and restores the flags after calling _CopyBits. You should never examine, set, or clear these flags directly; you should always use the routines which are provided by the Memory Manager and Resource Manager. Note that it is not necessary to check the value of the flag after getting it.
/* restore the resource's locked/unlocked condition */
HSetState((Handle) theSICN, state);
}
}
That Was Easy
Now that you’ve seen it done, it looks pretty easy. With minor modifications, some of the techniques in this Note could also be used to plot a bitmap of any dimension.
Inspired by: Jim Friedlander, Rick Blair, and Rich Collyer
Using Color QuickDraw to draw off screen is a common requirement of applications and other kinds of programs that run on the Macintosh. This Note discusses what Color QuickDraw needs in a graphics environment and how to create one for off-screen drawing. A brief discussion of GWorlds, which are off-screen graphics environments that are set up by the system, is given to help you decide whether to use them or the do-it-yourself techniques described in this Note for setting up an off-screen graphics environment. The author’s intent is to provide concepts and routines for creating an off-screen graphics environment, and also to explain why existing routines for off-screen drawing act as they do.
Many, many thanks go to Guillermo Ortiz, Konstantin Othmer, Bruce Leak, and Jon Zap for all their expertise on this subject, Rich Collyer, Rick Blair, and Jim Friedlander for paving the way, and especially to all people who inspired this update by asking great off-screen drawing questions.
Changes since October 1991: A very embarrassing bug was found in CreateOffScreen and UpdateOffScreen. If you try to create a 16- or 32-bit off-screen graphics environment, you’ll just get a paramErr. It won’t do that now.
Off-Screening
The Macintosh, as with every other CPU ever made by Apple, has memory-mapped video. That is, what you see on the screen is just the visual representation of a part of memory that’s reserved for the video hardware (that’s stretching the truth just a bit in the case of the text screens of the original Apple computer, the Apple II line, and the Apple III because there’s also a character generator in those, but the overall process still looks roughly the same). If you change the contents of a memory location in this part of memory, then you’ll see the corresponding location on the screen change when the video hardware draws the next frame or field of video. The resident raster graphics package, QuickDraw in the case of the Macintosh, draws images by stuffing the right values into the right places in the part of memory reserved for the video display. The resulting image on the screen looks like a line or perhaps an oval if you asked QuickDraw to draw a line or an oval, or it could be an entire complex image if you asked QuickDraw to draw one. This is normal, on-screen drawing.
Because video memory is a part of RAM just like any other part of RAM in the memory map of the Macintosh (or almost like; video memory might exist on a NuBus™ video card, but it’s still RAM), QuickDraw can be told to draw into a part of memory that isn’t reserved for the video hardware, maybe into a part of your own application’s heap. When you tell QuickDraw to draw into a part of memory that’s not reserved for the video hardware, you can’t see any of the results. This is off-screen drawing. There are plenty of perfectly good reasons to do this, such as providing storage for a paint-style document or to smoothly animate an image, but the assumption here is that you have a perfectly good reason to do this so you’re more interested in the “how” of it instead of the “why” of it. If you need to know why, there are several books that cover off-screen drawing and the perfectly good reasons to do such a thing. A good place to start is Scott Knaster’s book, Macintosh Programming Secrets, referenced at the end of this Note.
This Note is divided into these major sections:
• The introduction is the part that you’re reading now.
• “The Building Blocks” provides an overview of the data structures that you need to tell Color QuickDraw to draw off screen.
• “Building the Blocks” discusses the construction and initialization of these data structures.
• “Playing With Blocks” shows an example of the use of these structures to draw off screen.
• “Put That Checkbook Away!” discusses some variations of these techniques to handle off-screen drawing for special cases.
• “The GWorld Factor” provides a brief overview of GWorlds, how to use them, and how they compare and contrast to the manual techniques that are described in most of this Note.
Those of you who aren’t quite sure whether to use GWorlds or the do-it-yourself techniques might want to skip ahead for a moment to “The GWorld Factor” just in case doing it yourself is a waste of time. In any case, it’s a good idea to read this whole Note because the concepts are mostly the same whether you’re using GWorlds or not. GWorlds just make the process a lot easier, and they let you take advantage of the 8•24 GC video card. But, we’re not in that section of the Note yet.
The Building Blocks
Before you can tell QuickDraw to draw off of the screen, you’ll need to build three major data structures: a CGrafPort, a PixMap, and a GDevice. You’ll also need a couple of tables that define the colors involved with drawing to and copying from the off-screen image: the color table and the inverse table. Of course, you’ll need the pixel image itself, which is often called the “pixel buffer” or the “image buffer” or the “off-screen buffer” or just “the buffer.” It’s always called the “pixel image” in this Note. It doesn’t necessarily buffer anything anyway.
The CGrafPort
A CGrafPort describes a drawing environment, and it’s the color version of the GrafPort structure that’s described on pages 147 through 155 in the QuickDraw chapter of Inside Macintosh Volume I. The drawing environment consists of, among other things, the size and location of the graphics pen, the foreground and background colors to use when something is drawn, the pattern to use, the region to clip all drawing to, and the portion of a pixel image that the CGrafPort logically exists in. Any initialized CGrafPort or GrafPort can be set as the current port through the _SetPort routine. The current port is a set of parameters that are implicitly passed to most QuickDraw routines.
The most important reason to build a new CGrafPort when you draw off screen rather than using an existing CGrafPort is so that switching between drawing to an off-screen graphics environment and drawing to one or more windows (each of which is an extended GrafPort or CGrafPort structure) on the screen is very easy. Some people use just one CGrafPort to share between on-screen and off-screen graphics environments, and switch their PixMap structures to switch between drawing on screen and drawing off screen. That does work, but if the off-screen and on-screen graphics environments have a different clipRgn, visRgn, pen characteristic, portRect, or any other characteristics that are different, then those must be switched at that time too. If you instead create a CGrafPort that’s dedicated to one graphics environment, then a simple call to _SetPort effectively switches all these things for you at once. That’s why every window on the screen comes with its own port. A simple call to _SetPort switches between the characteristics of each window even if each window has radically different drawing characteristics.
The CGrafPort data structure is more completely described in the “Color QuickDraw” chapter of Inside Macintosh Volume V, pages 49 through 52, and in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 16-12 through 16-13.
The PixMap
A pixel image alone is just a formless blob of memory. Pixel maps, defined by the PixMap structure, describe pixel images, giving them a form and structure that’s suitable for Color QuickDraw to draw into them and copy from them. The PixMap structure tells you the dimensions and location in memory of the pixel image, its coordinate system, and the depth and format of the pixels. Pixel maps that describe indexed-color pixel images additionally describe the colors that are represented by the values of the pixels in the pixel image. This is done through the color table, also known as the color look-up table or CLUT. Color tables are attached to pixel maps through their pmTable field. Direct-color pixel images have pixel values that describe their own colors, and so color tables aren’t needed for those.
The PixMap structure is described in the “Color QuickDraw” chapter of Inside Macintosh Volume V, pages 52 through 55, and in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 16-11 through 16-12. The concept of direct-color and indexed-color pixels is described in this same chapter on pages 16-16 through 16-18, and also in the “Color QuickDraw” chapter of the same volume on pages 17-4 through 17-10.
The GDevice
Graphics devices, defined by the GDevice structure, describe color environments. They’re the most misunderstood data structure when it comes to off-screen graphics environments for three major reasons: first, they’re not originally documented as being relevant to humans; second, they look as though they’re only for screens; and third, it looks as though color tables describe color environments. We can dispose of these myths here: graphics devices are documented as being useful to humanity in this Note at least; they’re critically important for both on-screen and off-screen drawing; and color tables describe the colors in pixel images, not color environments.
What’s all this about color environments? In theory, there are virtually three hundred trillion colors available with Color QuickDraw through the 48-bit RGBColor record. In reality, there are never this many colors available, and in fact there might be only two. Color QuickDraw maps the theoretical color that you specify to the pixel value of the closest available color in the current color environment. This can be done with a color table, but that’s not very efficient. Finding the closest available color to an RGBColor in a color table means searching the entire color table for that one closest color. If that’s done just once, then performance isn’t much of an issue, but if it’s done many times, the performance hit could be significant. A very bad case of this is _CopyBits, where every pixel value in the source image is converted to an RGBColor by looking it up in the color table of the source PixMap. If the color table of the destination PixMap had to be searched to find the closest available color for every pixel in the source PixMap, then the performance of even the most straightforward _CopyBits call could be a lot slower than it has to be.
To avoid this performance hit, the current GDevice provides an inverse table and a device type which are used to determine the available set of colors. Inverse tables are anticolor tables. Where color tables give you a color for a given pixel value, inverse tables give you a pixel value for a given color. Every conceivable color table has a corresponding conceivable inverse table, just as every positive real number has a corresponding negative real number, or every Mr. Spock has a corresponding Mr. Spock with a goatee. The device type specifies whether the color environment uses the indexed-color, fixed-color, or direct-color model. In the direct-color model, the inverse table is empty. Only the indexed-color and direct-color models are described in this Note.
When you specify a color in an indexed-color environment, Color QuickDraw takes the RGBColor specification and converts it into a value that can be used as an index into the inverse table of the current GDevice. To do this conversion, Color QuickDraw takes the top few significant bits of each color component and combines them into part of a 16-bit word, blue bits in the least significant bits, green bits right above it, and the red bits right above green bits. Any unused bits are in the most significant bits of the 16-bit word. The resulting 16-bit word is used as an index into the inverse table. The value in the inverse table at that index is the pixel value which best represents that color in the current color environment. The number of bits of each component that are used is determined by what’s called the “resolution” of the inverse table. Almost always, the resolution of an inverse table is four bits, meaning the most significant four bits of each component are used to form the index into the inverse table. Figure 1 shows how an RGBColor record is converted to an index into an inverse table when the inverse-table resolution is four.
Figure 1 Conversion of RGBColor Record to Inverse-Table Index
The same process is used when _CopyBits is called with an indexed-color destination. Each pixel in the source pixel image is converted to an RGBColor either by doing a table look-up of the source pixel map’s color table if the source pixel image uses indexed colors, or by expanding the pixel value to an RGBColor record if the source pixel image uses direct colors. The resulting RGBColor is then used to look up a pixel value in the inverse table of the current GDevice, and this pixel value is put into the destination pixel image.
If you specify a color in a direct-color environment, then the resulting RGBColor is converted to a direct pixel value by the processes that are shown on pages 17-6 through 17-9 of the “Color QuickDraw” chapter of Inside Macintosh Volume VI.
Usually, inverse-table look-up involves an extra step to find what are called “hidden colors” using proprietary information that’s stored at the end of the inverse table. With an inverse-table resolution of four, only 16 shades of any particular component can be distinguished, and that’s often not enough. An inverse table with a resolution of five is much larger, but it still only gives you 32 shades of any component. Hidden colors are looked up after the normal inverse-table look-up to give a much more accurate representation of the specified color in the current color environment than the inverse-table look-up alone can produce. Sometimes, most notably when the arithmetic transfer modes are used or if dithering is used, the hidden colors are ignored.
When a new color table is assigned to a PixMap or when its existing color table is modified, then a new corresponding inverse table should be generated for the GDevice that’ll be used when drawing into that environment. Normally, this happens automatically without you having to do any more than inform Color QuickDraw of the change. This is described in more detail in “Changing the Off-Screen Color Table” later in this Note.
Graphics devices are documented in the “Graphics Devices” chapter of Inside Macintosh Volume VI which supersedes the “Graphics Devices” chapter of Inside Macintosh Volume V. They’re also discussed in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 16-13 through 16-14. The inverse-table mechanism is described in the “Color Manager” chapter of Inside Macintosh Volume V, pages 137 through 139.
All Together Now
There are a lot of different ways to put the three structures together, and this Note discusses the architecture that’s shown in Figure 2. This architecture is useful when you want a simple, atomic, off-screen graphics environment.
Figure 2 Relationships Between Structures for Off-Screen Drawing
Notice that there’s no way to get to the GDevice from the CGrafPort, nor is there a way to get to the CGrafPort from the GDevice, though the PixMap can be found through either one. Your application must keep track of both the CGrafPort and the GDevice.
Building the Blocks
As with just about any algorithm, there are many ways to put the different structures together that form an off-screen graphics environment. This section covers just one way to build the architecture that’s shown in Figure 2.
Building the CGrafPort
The CGrafPort structure is the easiest one to put together because the _OpenCPort routine initializes so many of the fields of the CGrafPort structure for you. It also allocates and initializes the structures that are attached to every CGrafPort, such as the visRgn, clipRgn, grafVars handle, and so forth. Most of these are initialized with values that are fine for general purposes, but the visRgn, clipRgn, and portRect fields should be set to the desired boundary rectangle of the off-screen graphics environment. What follows is an overview of each of the fields that you have to worry about when you’re setting up a CGrafPort for drawing off screen.
portPixMap handle to the off-screen PixMap. _OpenCPort initializes this field to a copy of the PixMap that’s attached to the gdPMap field of the current GDevice. An overview of setting up this PixMap for drawing off screen is given in “Building the PixMap” later in this Note.
portRect specifies the rectangular area of the associated pixel image that this CGrafPort controls. This field should be set to the desired rectangular area of the off-screen image because _OpenCPort doesn’t necessarily initialize it to this size. Usually, the top-left corner of this rectangle has the coordinates (0, 0), but not necessarily so.
visRgn handle to the region that specifies the visible area into which you can draw. _OpenCPort doesn’t necessarily initialize it to the size of the off-screen image, so it should be set to the same size and coordinates as the portRect and left at that. This field is more important for windows because parts of them can be hidden by other windows.
clipRgn handle to the region that specifies the logical area into which you can draw. _OpenCPort initializes it to cover the entire QuickDraw coordinate plane. It’s usually a good idea to set it to the same size and coordinates as the portRect to avoid problems if the clipRgn is scaled or translated, which causes its signed integer coordinates to overflow and turn it into an empty region. One of the most common cases of this occurs when a picture that’s created in this CGrafPort is drawn into a destination rectangle that’s any larger than or translated from the original picture frame. Everything in the picture, including the clip region, is scaled to fit the destination rectangle. If the clip region covers the entire QuickDraw coordinate plane, then its coordinates overflow their signed integer bounds, and the clip region becomes logically empty. The result is that nothing is drawn.
The CreateOffScreen routine in Listing 1 creates an off-screen graphics environment, given a boundary rectangle, pixel depth, and color table, and it returns a new off-screen CGrafPort and GDevice, along with an error code. The desired pixel depth in bits per pixel is given in the depth parameter. If the pixel depth is eight or less, then an indexed-color graphics environment is created and a color table is required in the colors parameter. If the pixel depth is 16 or 32 bits per pixel and 32-Bit QuickDraw is available, then a direct-color graphics environment is created and the colors parameter is ignored. If 32-Bit QuickDraw isn’t available, then a pixel depth of 16 or 32 bits per pixel results in CreateOffScreen doing nothing more than returning a parameter error. A description of CreateOffScreen is given following the listing.
MPW Pascal Listing 1
FUNCTION CreateOffScreen(
bounds: Rect; {Bounding rectangle of off-screen}
depth: Integer; {Desired number of bits per pixel in off-screen}
colors: CTabHandle; {Color table to assign to off-screen}
VAR retPort: CGrafPtr; {Returns a pointer to the new CGrafPort}
VAR retGDevice: GDHandle {Returns a handle to the new GDevice}
): OSErr;
CONST
kMaxRowBytes = $3FFE; {Maximum number of bytes in a row of pixels}
VAR
newPort: CGrafPtr; {Pointer to the new off-screen CGrafPort}
newPixMap: PixMapHandle; {Handle to the new off-screen PixMap}
newDevice: GDHandle; {Handle to the new off-screen GDevice}
qdVersion: LongInt; {Version of QuickDraw currently in use}
savedPort: GrafPtr; {Pointer to GrafPort used for save/restore}
savedState: SignedByte; {Saved state of color table handle}
bytesPerRow: Integer; {Number of bytes per row in the PixMap}
error: OSErr; {Returns error code}
BEGIN
(* Initialize a few things before we begin *)
newPort := NIL;
newPixMap := NIL;
newDevice := NIL;
error := noErr;
(* Save the color table’s current state and make sure it isn’t purgeable *)
IF colors <> NIL THEN
BEGIN
savedState := HGetState(Handle(colors));
HNoPurge(Handle(colors));
END;
(* Calculate the number of bytes per row in the off-screen PixMap *)
/* One Last Look Around The House Before We Go… */
if (error != noErr)
{
/* Some error occurred; dispose of everything we allocated */
if (newPixMap != nil)
{
DisposCTable( (**newPixMap).pmTable );
DisposPtr( (**newPixMap).baseAddr );
}
if (newDevice != nil)
{
DisposHandle( (Handle)(**newDevice).gdITable );
DisposHandle( (Handle)newDevice );
}
if (newPort != nil)
{
CloseCPort( newPort );
DisposPtr( (Ptr)newPort );
}
}
else
{
/* Everything’s OK; return refs to off-screen CGrafPort and GDevice */
*retPort = newPort;
*retGDevice = newDevice;
}
return error;
}
CreateOffScreen begins by making sure that the color table, if there is one, doesn’t get purged during the time that the off-screen graphics environment is created. Then, a sanity check is done for the given depth, bounds, and color table. The depth must be either 1, 2, 4, or 8 bits per pixel, or additionally 16 or 32 bits per pixel if 32-Bit QuickDraw is available. If these conditions aren’t satisfied, then it’s decided that there’s an error in the parameter list, and CreateOffScreen does nothing more. To determine whether 32-Bit QuickDraw is available or not, the _Gestalt routine is used. If _Gestalt returns a value that’s equal to or greater than the constant gestalt32BitQD, then 32-Bit QuickDraw is available and depths of 16 and 32 bits per pixel are supported. It’s not necessary to determine whether _Gestalt is available or not because it’s implemented as glue code in the Macintosh Programmer’s Workshop.
A check is then done to determine whether the number of bytes in each row of the off-screen pixel image is too much for QuickDraw to handle. Color QuickDraw can handle up to and including 16,382 ($3FFE) bytes in each row of any pixel image. If the required number of bytes per row exceeds this amount, then CreateOffScreen decides that there’s an error in the parameter list and does nothing more. The minimum number of bytes in a row that’s enough to cover the given boundary rectangle at the given pixel depth is calculated with the formula:
This formula multiplies the number of pixels across the PixMap by the pixel depth to get the number of bits, and then this is divided by eight to get the number of bytes. This division by eight looks very strange because the number of bytes per row must be even, so this formula takes advantage of integer division and multiplication to make the result come out even. This particular formula additionally makes sure that the number of bytes per row is a multiple of four. This helps optimize the performance of Color QuickDraw operations because it allows Color QuickDraw to refer to each row beginning on a long word boundary in memory.
The last sanity check is to make sure that a color table is given as a parameter if it’s needed. Indexed-color graphics environments need color tables, so if the given pixel depth is eight or less (which implies an indexed-color graphics environment) and the given color table is NIL, then CreateOffScreen decides that there’s an error in the parameter list and does nothing more. If the given pixel depth is 16 or 32 (which implies a direct-color graphics environment), then CreateOffScreen ignores the given color table.
If all the sanity checks succeed, then the off-screen CGrafPort is allocated using a call to _NewPtr, and then it’s initialized and opened as a CGrafPort by passing the resulting pointer to _OpenCPort. Because _OpenCPort makes the new CGrafPort the current port, the current port is first saved so that it can be restored as the current port when CreateOffScreen is done.
As mentioned above, the _OpenCPort doesn’t necessarily initialize the portRect, visRgn, and clipRgn of the new CGrafPort to the areas that are needed for any particular off-screen graphics environment. So, the given boundary rectangle is assigned to the portRect field, _RectRgn is called to make the visRgn equal to the given boundary rectangle, and _ClipRect is called to set the clipRgn so that it’s equal to the given boundary rectangle.
The PixMap in the portPixMap field needs to be initialized for off-screen drawing, and that’s handled by the SetUpPixMap routine that’s described and defined in “Building the PixMap” later in this Note. Similarly, the off-screen GDevice must be created and initialized. That’s handled by the CreateGDevice routine that’s described and defined in “Building the GDevice” later in this Note.
Once these things are done, CreateOffScreen returns a pointer to the off-screen CGrafPort in the retPort parameter and a handle to the off-screen GDevice in the retGDevice parameter. The way to use these references is described in “Playing With Blocks” later in this Note.
Building the PixMap
_OpenCPort initializes the portPixMap field of the CGrafPort it’s initializing with a copy of the PixMap of the current GDevice. When the CreateOffScreen routine described earlier executes, the current GDevice is unknown. So, all the fields of the PixMap that the new CGrafPort receives must be initialized so that it can be used for drawing off screen.* What follows is an overview of each of the PixMap fields and how they should be initialized for off-screen drawing.
baseAddr pointer to the off-screen pixel image. The off-screen pixel image is allocated as a nonrelocatable block in the heap. The size of this block of memory is calculated from the rowBytes field, described next, multiplied by the number of rows in the given boundary rectangle.
rowBytes number of bytes in each row of the pixel image. This value is calculated from the formula that’s given in the CreateOffScreen routine. The most significant bit of this field should be set so that Color QuickDraw knows that this is a PixMap rather than a BitMap. The maximum value, ignoring the most significant bit, is 16,382.
bounds defines the coordinate system and the dimensions of the pixel image. For most off-screen drawing, this should be a rectangle that covers the entire off-screen graphics environment.
pmVersion set of internally and externally defined flags. As of 32-Bit QuickDraw 1.2, only the baseAddr32 flag is defined externally. This flag is described in “Choosing Your Off-Screen Memory” later in this Note. For most off-screen drawing, this field is set to zero.
packType image compression scheme for pictures. The options for this field are discussed in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 17-22 through 17-23. In this Note, image compression isn’t discussed so this field is set to zero.
packSize internally used field. This field is always set to zero.
hRes horizontal resolution of the pixel map. By default, the QuickDraw resolution is 72 dots per inch,which is the value this Note uses. This is a fixed-point field, so the actual value in this field is $00480000.
vRes vertical resolution of the pixel map. See the hRes description.
pixelType format of the pixels. In indexed-color pixel maps, this field holds zero. In direct-color pixel maps, this field holds the RGBDirect constant, which is equal to 16.
pixelSize number of bits in every pixel. For indexed-color pixels, this is 1, 2, 4, or 8 bits per pixel. For direct-color pixels, this is 16 or 32 bits per pixel.
cmpCount number of components in every pixel. In indexed-color pixel maps, this field is set to 1. In direct-color pixel maps, this field is set to 3. Sometimes it’s handy to set this field to 4 in 32-bit deep pixel maps when they’re being saved in a picture. See the “Color QuickDraw” chapter of Inside Macintosh Volume VI, page 17-23, for details about this.
cmpSize number of bits in each color component. In indexed-color pixel maps, this field is set to the same value that’s in the pixelSize field. In 16-bit deep direct pixel maps, this field is set to 5. In 32-bit deep direct pixel maps, this field is set to 8.
planeBytes not currently defined. This field is set to zero.
pmTable handle to the color table for indexed-color pixel maps. A method to create a color table is given in “About That Creation Thing . . .” later in this Note. In direct-color pixel maps, this field contains a handle to a dummy color table, and building one of these is shown in the SetUpPixMap routine in Listing 2.
pmReserved not currently defined. This field is set to zero.
(*This part of these routines really bothers me because it feels impure to initialize all the PixMap fields when _OpenCPort has initialized them already, just not in a way that’s any good for off-screen drawing. I tried creating the GDevice and PixMap first and then calling _OpenCPort so that it initializes its PixMap for off-screen drawing, but then you end up with two pixel maps and that makes this tougher to explain, or you have to dispose of one PixMap which seems worse than the method I’m using.)
The SetUpPixMap routine in Listing 2 initializes the PixMap that’s passed to it in the aPixMap parameter so that it can be used in an off-screen graphics environment. The depth, bounds, and color parameters are the same as the ones passed to the CreateOffScreen routine. The bytesPerRow parameter is the number of bytes in each row of the off-screen pixel image. A description of SetUpPixMap follows the listing.
MPW Pascal Listing 2
FUNCTION SetUpPixMap(
depth: Integer; {Desired number of bits/pixel in off-screen}
bound: Rect; {Bounding rectangle of off-screen}
colors: CTabHandle; {Color table to assign to off-screen}
bytesPerRow: Integer; {Number of bytes in each row of pixels}
aPixMap: PixMapHandle {Handle to the PixMap being initialized}
): OSErr;
CONST
kDefaultRes = $00480000; {Default resolution is 72 DPI; Fixed type}
VAR
newColors: CTabHandle; {Color table used for the off-screen PixMap}
offBaseAddr: Ptr; {Pointer to the off-screen pixel image}
error: OSErr; {Returns error code}
BEGIN
error := noErr;
newColors := NIL;
offBaseAddr := NIL;
(* Clone the clut if indexed color; allocate a dummy clut if direct color *)
(**aPixMap).pmTable = newColors; /* Handle to CLUT */
}
else
{
/* PixMap is direct */
(**aPixMap).pixelType = RGBDirect; /* Indicates direct */
(**aPixMap).cmpCount = 3; /* Have 3 components */
if (depth == 16)
(**aPixMap).cmpSize = 5; /* 5 bits/component */
else
(**aPixMap).cmpSize = 8; /* 8 bits/component */
(**newColors).ctSeed = 3 * (**aPixMap).cmpSize;
(**newColors).ctFlags = 0;
(**newColors).ctSize = 0;
(**aPixMap).pmTable = newColors;
}
}
else
error = MemError();
}
else
newColors = nil;
/* If no errors occurred, return a handle to the new off-screen PixMap */
if (error != noErr)
{
if (newColors != nil)
DisposCTable( newColors );
}
/* Return the error code */
return error;
}
SetUpPixMap begins by copying the given color table if an indexed-color graphics environment is being built, or allocating a dummy color table if a direct-color graphics environment is being built. A copy of the color table is made because this allows the given color table and the off-screen graphics environment’s color table to be manipulated independently without interfering with each other, and this lets the off-screen graphics environment routines manipulate the color table without needing to worry about whether the color table is a 'clut' resource or not. The dummy color table is made so that routines which assume that every PixMap has a color table won’t do something catastrophic if they find a NIL color table. The off-screen pixel image is then allocated as a nonrelocatable block in the application’s heap.
Some of the fields of a PixMap have to be initialized differently depending upon whether the indexed-color model or the direct-color model is being used. So, the fields that are the same regardless of the color model that’s being used are assigned first. Then the desired pixel depth is compared to 8. If the depth is less than or equal to 8, then the rest of the fields are initialized for the indexed-color model. Otherwise, the rest of the fields are initialized for the direct color model. In the case of the direct-color model, the dummy color table is initialized to have no CSpecArray entries and its ctSeed field is set to three times the component size. This dummy color table is then installed into the PixMap.
Once SetUpPixMap completes, the PixMap of the new CGrafPort is ready to hold an off-screen image. It’s not quite ready to be drawn into with Color QuickDraw though. To do that, the off-screen GDevice is still needed; the construction and initialization of the GDevice are covered in the next section.
Building the GDevice
The _OpenCPort routine automatically allocates and initializes a PixMap, and the SetUpPixMap routine reinitializes that existing PixMap. _OpenCPort doesn’t allocate nor initialize a GDevice, so one has to be created from scratch. Pages 21-20 through 21-21 of “The Graphics Devices Manager” chapter of Inside Macintosh Volume VI describe the _NewGDevice routine. This routine seems as though it’s the ticket to getting a GDevice for off-screen drawing, but it always allocates the new GDevice in the system heap. That’s not so good because if your program unexpectedly quits or if you just forget to dispose of the GDevice before you quit for real, the GDevice gets orphaned in the system heap. To prevent this from happening, _NewGDevice should be ignored and the off-screen GDevice should instead be allocated and initialized from scratch. What follows is a description of how each field of the GDevice structure should be initialized.
gdRefNum reference number of video driver. Off-screen graphics environments don’t need to have video drivers because there’s no video device associated with them, so this field is set to zero.
gdID used to identify specific GDevice structures from color-search procedures. This isn’t necessary for off-screen drawing, so this is normally set to zero.
gdType type of GDevice. This field is set to the constant clutType (equal to zero) for an indexed-color environment and set to the constant directType (equal to 2) for a direct-color environment.
gdITable handle to the inverse table. Initially, this field is set to an arbitrarily small handle. Later, the _MakeITable routine is used to resize and initialize this handle to a real inverse table.
gdResPref inverse-table resolution. When _MakeITable is called by QuickDraw, the value of this field is used as the inverse-table resolution. Almost all inverse tables have a resolution of 4. There are some cases when a inverse-table resolution of 5 is useful, particularly when the arithmetic transfer modes are used with _CopyBits. See “The GDevice” earlier in this Note.
gdSearchProc pointer to the color-search procedure. If a color-search procedure is needed, this field can be set later by calling the _AddSearch routine (see the “Color Manager” chapter of Inside Macintosh Volume V, pages 145 through 147). Usually, this field is just set to NIL and left at that.
gdCompProc pointer to the color-complement procedure. If a color-complement procedure is needed, this field can be set later by calling the _AddComp routine (see the “Color Manager” chapter of Inside Macintosh Volume V, pages 145 through 147). Usually, this field is set to NIL and left at that.
gdFlags flags indicating certain states of the GDevice. This field should initially be set to zeroes. After the GDevice has been built, these flags can be set with the _SetDeviceAttrs routine (see the “Graphics Devices Manager” chapter of Inside Macintosh Volume VI, pages 21-10 and 21-22).
gdPMap handle to a PixMap. A handle to the PixMap of the CGrafPort that was created earlier is put into this field.
gdRefCon miscellaneous data. _CalcCMask and _SeedCFill use this field as described on pages 71 through 72 of Inside Macintosh Volume V. Initially, this field is set to zero.
gdNextGD handle to next GDevice in the GDevice list. The system maintains a linked list of GDevice records in which there’s one GDevice for every screen, and the links are kept in this field. Off-screen GDevice structures should never be put into this list, so this field should be set to NIL.
gdRect rectangle of GDevice. Strictly speaking, this field is used only for screens, but it should be the same as the bounds rectangle of the off-screen PixMap.
gdMode current video mode. This field is used by video drivers to keep track of the current mode that the video device is in. For off-screen GDevice structures, this field should be set to -1.
gdCC… These four fields are used only with GDevice structures for screens. For off-screen GDevice structures, these fields should be set to zero.
gdReserved not currently defined. This field is set to zero.
The CreateGDevice routine shown below in Listing 3 allocates and initializes a GDevice structure. It takes the initialized off-screen PixMap in the basePixMap parameter and returns the initialized GDevice in the retGDevice parameter. If any error occurs, any memory that’s allocated is disposed of and the result code is returned as a function result.
MPW Pascal Listing 3
FUNCTION CreateGDevice(
basePixMap: PixMapHandle; {Handle to the PixMap to base GDevice on}
VAR retGDevice: GDHandle {Returns a handle to the new GDevice}
): OSErr;
CONST
kITabRes = 4; {Inverse-table resolution}
VAR
newDevice: GDHandle; {Handle to the new GDevice}
embryoITab: ITabHandle; {Handle to the embryonic inverse table}
CreateGDevice begins by allocating the GDevice structure and an embryonic form of the inverse table in the current heap. The inverse table is allocated as two zero bytes for now; it’ll be resized and initialized to be a real inverse table later in this routine. Then, each of the GDevice fields are initialized as described earlier.
After all the fields have been initialized, the gdFlags field is set through _SetDeviceAttribute. If the desired pixel depth is greater than 1, then the gdDevType bit is set. This indicates that the GDevice is for a color graphics environment. This bit should be set even if a gray-scale color table is used for this off-screen graphics environment. The noDriver bit is set because this is an off-screen GDevice and so there’s no associated video device driver.
Finally, the inverse table is resized and initialized by calling the _MakeITable routine. A handle to the two-byte embryonic inverse table that was created earlier in CreateGDevice is passed as a parameter, as is a handle to the off-screen color table and the preferred inverse-table resolution.
All Fall Down
Now that we have a way to create an off-screen graphics environment, there has to be a way to get rid of it too. The DisposeOffScreen routine shown in Listing 4 does this. The CreateOffScreen routine returns an off-screen graphics environment that’s represented by a CGrafPort and GDevice. The DisposeOffScreen routine takes the off-screen CGrafPort and GDevice and deallocates all the memory that’s associated with them including the CGrafPort and its dependent structures, the GDevice, the PixMap, the color table, and the inverse table.
MPW Pascal Listing 4
PROCEDURE DisposeOffScreen(
doomedPort: CGrafPtr; {Pointer to the CGrafPort we’re getting rid of}
doomedGDevice: GDHandle {Handle to the GDevice we’re getting rid of}
);
VAR
currPort: CGrafPtr; {Pointer to the current port}
currGDevice: GDHandle; {Handle to the current GDevice}
BEGIN
(* Check to see whether the doomed CGrafPort is the current port *)
GetPort(GrafPtr(currPort));
IF currPort = doomedPort THEN
BEGIN
(* It is; set current port to Window Manager CGrafPort *)
GetCWMgrPort(currPort);
SetPort(GrafPtr(currPort));
END;
(* Check to see whether the doomed GDevice is the current GDevice *)
currGDevice := GetGDevice;
IF currGDevice = doomedGDevice THEN
(* It is; set current GDevice to the main screen’s GDevice *)
SetGDevice(GetMainDevice);
(* Throw everything away *)
doomedGDevice^^.gdPMap := NIL;
DisposGDevice(doomedGDevice);
DisposPtr(doomedPort^.portPixMap^^.baseAddr);
IF doomedPort^.portPixMap^^.pmTable <> NIL THEN
DisposCTable(doomedPort^.portPixMap^^.pmTable);
CloseCPort(doomedPort);
DisposPtr(Ptr(doomedPort));
END;
MPW C Listing 4
void DisposeOffScreen(
CGrafPtr doomedPort, /* Pointer to the CGrafPort to be disposed of */
GDHandle doomedGDevice) /* Handle to the GDevice to be disposed of */
{
CGrafPtr currPort; /* Pointer to the current port */
GDHandle currGDevice; /* Handle to the current GDevice */
/* Check to see whether the doomed CGrafPort is the current port */
GetPort( (GrafPtr *)&currPort );
if (currPort == doomedPort)
{
/* It is; set current port to Window Manager CGrafPort */
GetCWMgrPort( &currPort );
SetPort( (GrafPtr)currPort );
}
/* Check to see whether the doomed GDevice is the current GDevice */
currGDevice = GetGDevice();
if (currGDevice == doomedGDevice)
/* It is; set current GDevice to the main screen’s GDevice */
One mildly tricky aspect of this is that we shouldn’t dispose of the current graphics environment. To prevent this, the current port is retrieved by a call to _GetPort. If it returns a pointer to the same port that DisposeOffScreen is disposing, then the current port is set to the Window Manager’s CGrafPort. That was an arbitrary choice, but it’s the most neutral. Similarly, the current GDevice is retrieved by a call to _GetGDevice. If it returns a handle to the same GDevice that DisposeOffScreen is disposing, then the current port is set to the main screen’s GDevice. Again, that’s an arbitrary, neutral choice.
The inverse table, GDevice, pixel image, and color table are disposed of. Before disposing of the color table, a check is first made to see whether it’s NIL. That’s because it’s reasonable, though not normal, for the PixMap not to have even a dummy color table if the direct-color model is being used. Then the CGrafPort is closed which deallocates all the pieces associated with the CGrafPort, including the PixMap. Once this is done, all the structures that were created by calling CreateOffScreen are deallocated.
Playing With Blocks
Now that these four routines with two entry points can create and dispose of off-screen graphics environments, how are they used? There are several phases to using an off-screen graphics environment: creating it, drawing into it, switching between it and other off-screen and on-screen graphics environments, copying images to and from it, and disposing of it. Listing 5 shows a routine called ExerciseOffScreen which is a very basic example of all of these phases.
MPW Pascal Listing 5
PROCEDURE ExerciseOffScreen;
CONST
kOffDepth = 8; {Number of bits per pixel in off-screen environment}
rGrayClut = 1600; {Resource ID of gray-scale clut}
rColorClut = 1601; {Resource ID of full-color clut}
VAR
grayPort: CGrafPtr; {Graphics environment for gray off screen}
grayDevice: GDHandle; {Color environment for gray off screen}
colorPort: CGrafPtr; {Graphics environment for color off screen}
colorDevice: GDHandle; {Color environment for color off screen}
savedPort: GrafPtr; {Pointer to the saved graphics environment}
savedDevice: GDHandle; {Handle to the saved color environment}
offColors: CTabHandle; {Colors for off-screen environments}
offRect: Rect; {Rectangle of off-screen environments}
circleRect: Rect; {Rectangles for circle-drawing}
count: Integer; {Generic counter}
aColor: RGBColor; {Color used for drawing off screen}
error: OSErr; {Error return from off-screen creation}
BEGIN
(* Set up the rectangle for the off-screen graphics environments *)
SetRect(offRect, 0, 0, 256, 256);
(* Get the color table for the gray off-screen graphics environment *)
offColors := GetCTable(rGrayClut);
(* Create the gray off-screen graphics environment *)
/* Dispose of the off-screen graphics environments */
DisposeOffScreen( grayPort, grayDevice );
DisposeOffScreen( colorPort, colorDevice );
}
}
}
Two off-screen graphics environments are created in the same way. A rectangle that’s 256 pixels wide by 256 pixels high and with its top-left coordinate at (0, 0) is created in the offRect local variable. 'clut' resources are loaded from the application’s resource fork to use as the color tables of the two off-screen graphics environments; a gray-scale 'clut' in the first case and a full-color 'clut' in the second case. Then, CreateOffScreen is called with the rectangle, color table, and a hard-coded pixel depth of eight bits per pixel.
If CreateOffScreen returns noErr in both cases, then the current graphics environment is saved so that it can be restored later. Graphics environments consist of the current port and the current GDevice. The current GrafPort or CGrafPort is saved with _GetPort. The current GDevice is saved with _GetGDevice.
The gray-scale off-screen graphics environment is set as the current graphics environment by calling _SetPort with its CGrafPort and calling _SetGDevice with its GDevice. A vertical gray ramp is drawn into this graphics environment with the usual set of QuickDraw calls. This graphics environment’s pixel image is then copied to the full-color off-screen graphics environment with dithering and colorization with green (dithering requires 32-Bit QuickDraw and consistent colorization requires system software version 7.0; both of these features are described in Konstantin Othmer’s article “QuickDraw’s CopyBits Procedure: Better Than Ever in System 7.0” in Issue 6 of develop). Before this copy happens, the full-color off-screen graphics environment must be set as the current one. Once this is done, _CopyBits can properly map colors from the gray-scale off-screen graphics environment to the full-color one which gets a green ramp image.
Red, green, and blue concentric circles are drawn into the full-color off-screen graphics environment over the green ramp. This image is then copied to the graphics environment that was the current one when ExerciseOffScreen was called. To do this, the saved graphics environment is set as the current one by what should now be the familiar calls to _SetPort and _SetGDevice. The off-screen image is then copied to the saved graphics environment with _CopyBits.
Finally, the two off-screen graphics environments are disposed of by calling the DisposeOffScreen routine that’s defined in the section “All Fall Down” earlier in this Note.
Put That Checkbook Away!
The previous section covered the basics of creating and using off-screen graphics environments. This is good enough for many, if not most, needs of off-screen drawing. But there are variations to creating and maintaining an off-screen graphics environment for specific cases. This section discusses a few of the more common cases.
About That Creation Thing . . .
The CreateOffScreen routine, defined in Listing 1, takes three pieces of information: the boundary rectangle, the desired pixel depth, and the desired color table. But there’s much more to these pieces than ExerciseOffScreen shows. This section describes these pieces in more detail.
The first parameter to CreateOffScreen is a rectangle which determines the size and coordinate system of the off-screen graphics environment. Usually, the top-left corner of the rectangle has the coordinate (0, 0) because it’s usually easiest to draw everything using coordinates that can also be thought of as the horizontal and vertical distance in pixels from the top-left corner of the graphics environment. But in some cases, it’s more convenient to have the (0, 0) coordinate somewhere else, and passing CreateOffScreen a rectangle with a nonzero coordinate in the top-left corner is an easy way to do this. The coordinate system can be translated after the off-screen graphics environment is created by using the _SetOrigin routine that’s described on pages 153 through 155 of Inside Macintosh Volume I.
Warning: As Inside Macintosh Volume I, page 154, notes, the clip region of the port “sticks” to the coordinate system when you call _SetOrigin. If _SetOrigin offsets the coordinate system by a large amount, then the clip region might be moved completely outside of the port’s drawing area, and nothing can be drawn into that port. After calling _SetOrigin, you should set the clip region so that you can continue drawing into the port.
The number of bits per pixel implies the maximum number of available colors in a graphics environment, at least roughly speaking. The relationship between the number of bits per pixel and the number of available colors is discussed in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 16-8 through 16-9.
If an indexed-color graphics environment is being made, then a color table must be passed to CreateOffScreen. In ExerciseOffScreen, the color table is retrieved from a 'clut' resource that’s in the application’s resource fork with a call to _GetCTable. Because CreateOffScreen clones this color table, this 'clut' resource can be purgeable so that it can be thrown out if its memory is needed for other purposes. _GetCTable can also be passed some special constants that tell it to allocate various system color tables that can also be passed to CreateOffScreen. These special constants are described on page 17-18 of the “Color QuickDraw” chapter of Inside Macintosh Volume VI. _GetCTable allocates memory for these system color tables, so they should be disposed of after you’re done with them.
A color table could also be built from scratch by allocating it with a call to _NewHandle and then initializing it by hand. The ColorTable structure is documented on pages 48 through 49 of Inside Macintosh Volume V. Here’s what each of the fields should be set to:
ctSeed identification value. This is an arbitrary value that should be changed any time the contents of the color table change so that the inverse table can be kept current. When Color QuickDraw draws anything, it compares the ctSeed of the color table of the PixMap of the current GDevice against the iTabSeed field of the inverse table of the current GDevice. If they’re the same, then Color QuickDraw uses colors according to that inverse table. If they’re different, then Color QuickDraw first rebuilds the inverse table according to the new color table’s contents and its iTabSeed is set to the value of the new color table’s ctSeed; then the rebuilt inverse table is used.
When _CopyBits is called with the srcCopy transfer mode, the ctSeed fields of the source and destination pixel maps are compared. If they’re the same, then _CopyBits simply transfers the source pixels to the destination with no mapping of colors. If they’re different, then _CopyBits checks each entry of the color tables to determine whether they have the same colors for the same pixel values. If they do, then _CopyBits again simply transfers the source pixels to the destination with no mapping of colors. If they don’t, then _CopyBits maps colors in the source PixMap to the colors in the current graphics environment according to the inverse table of the current GDevice. The ctSeed field of a color table should be changed whenever its contents are changed so that _CopyBits doesn’t make the wrong assumptions about the equality of the source and destination color tables.
You can get a seed value for a new color table by assigning to it the result of the _GetCTSeed routine, documented in the “Color Manager” chapter of Inside Macintosh Volume V, page 143. If the contents of an existing color table are changed, then it should be passed to the _CTabChanged routine which assigns a new value to its ctSeed field. If the _CTabChanged routine isn’t available (it’s available with 32-Bit QuickDraw and is included with the system beginning with system software version 7.0), then the ctSeed field should be given a new value with another call to _GetCTSeed.
ctFlags indicates the Boolean characteristics of a color table. If the most significant bit of ctFlags is clear, then the value field of each ColorSpec entry in the ctTable array is interpreted as the pixel value for the color that’s specified in the rgb field in the same ColorSpec entry. You can build a color table with nonconsecutive pixel values this way. If this bit is set, then all the value fields in the color table are ignored and the index of each ColorSpec record in the ctTable array is that record’s pixel value. It’s your choice whether to clear this bit and set the value fields or set this bit and ignore the value fields; traditionally this bit is clear for off-screen color tables.
If the next most significant bit of ctFlags is set, then the value field of each ColorSpec record in the ctTable array is used by _CopyBits as an index into the color palette that’s attached to the destination window, and the rgb field is ignored. This is documented in the “Palette Manager” chapter of Inside Macintosh Volume VI, page 20-17.
The other bits are reserved for future use. If you create a color table from scratch, these other bits must be set to zero. If you use a color table that’s generated by the system, then these bits must be preserved.
ctSize the number of color table entries minus 1. Normally, this field is set to 1, 3, 15, or 255 for 1-, 2-, 4-, and 8-bits per pixel, respectively. In special cases, it’s reasonable to have less than the maximum number of entries for the pixel depth. For example, a color table for an 8-bit per pixel graphics environment could have just 150 entries, in which case the ctSize field should hold 149. For this case, it’s still important to allocate as much space in the color table for the maximum number of entries for a pixel depth and clear the entries you’re not using to zero because some parts of Color QuickDraw assume the size of a color table based on the pixel depth.
ctTable array of colors and pixel values. This table defines all the available colors in the color table and their pixel values. The value field of each ColorSpec record indicates that color’s pixel value if the most significant bit of ctFlags is clear. It’s ignored if the most significant bit of ctFlags is set. The value field is used as an index into a palette if the next most significant bit of ctFlags is set, in which case the rgb field is ignored. See the discussion of the ctFlags field earlier in this Note for more details.
Warning: Color QuickDraw’s text-drawing routines assume that the color table of the destination graphics environment has the maximum number of colors for the pixel depth of the graphics environment, and that white is the first entry in the color table and black is the last entry. If these conditions aren’t satisfied, then the resulting image is unpredictable.
The code fragment in Listing 6 shows how to allocate a 256-entry color table from scratch. Color tables have a variable size, so the _NewHandle call has to calculate the size of the ColorTable record plus the maximum number of color table entries for the pixel depth multiplied by the size of a ColorSpec record. kNumColors - 1 is used in the calculation because the size of the ColorTable record includes the size of one ColorSpec entry in most development environments.
MPW Pascal Listing 6
CONST
kNumColors = 256; {Number of color table entries}
VAR
newColors: CTabHandle; {Handle to the new color table}
After you create an off-screen graphics environment with certain dimensions, you might later want to change its size, depth, or color table without creating a completely new graphics environment from scratch and without needing to redraw the existing image. The UpdateOffScreen routine in Listing 7 shows just one way to do this. It takes the same parameters that CreateOffScreen (defined in Listing 1) does, but instead of creating a new CGrafPort and GDevice, it alters the ones that you pass through the updPort and updGDevice parameters. If the newBounds parameter specifies an empty rectangle, then the existing boundary rectangle for the off-screen graphics environment is used. Similarly, if newDepth is zero, then the existing depth is used; and if the newColors parameter is NIL, then the existing color table is used. UpdateOffScreen alters the given CGrafPort and GDevice to the new settings, but it completely replaces the PixMap. After all the alterations are made, the old PixMap’s image is copied to the new PixMap’s image, and then the old PixMap and its image are disposed.
MPW Pascal Listing 7
FUNCTION UpdateOffScreen(
newBounds: Rect; {New bounding rectangle of off-screen}
newDepth: Integer; {New number of bits per pixel in off-screen}
newColors: CTabHandle; {New color table to assign to off-screen}
updPort: CGrafPtr; {Returns a pointer to the updated CGrafPort}
updGDevice: GDHandle {Returns a handle to the updated GDevice}
): OSErr;
CONST
kMaxRowBytes = $3FFE; {Maximum number of bytes per row of pixels}
VAR
newPixMap: PixMapHandle; {Handle to the new off-screen PixMap}
oldPixMap: PixMapHandle; {Handle to the old off-screen PixMap}
bounds: Rect; {Boundary rectangle of off-screen}
depth: Integer; {Depth of the off-screen PixMap}
bytesPerRow: Integer; {Number of bytes per row in the PixMap}
colors: CTabHandle; {Colors for the off-screen PixMap}
savedFore: RGBColor; {Saved foreground color}
savedBack: RGBColor; {Saved background color}
aColor: RGBColor; {Used to set foreground and background color}
qdVersion: LongInt; {Version of QuickDraw currently in use}
savedPort: GrafPtr; {Pointer to GrafPort used for save/restore}
savedDevice: GDHandle; {Handle to GDevice used for save/restore}
savedState: SignedByte; {Saved state of color table handle}
error: OSErr; {Returns error code}
BEGIN
(* Initialize a few things before we begin *)
newPixMap := NIL;
error := noErr;
(* Keep the old bounds rectangle, or get the new one *)
IF EmptyRect(newBounds) THEN
bounds := updPort^.portRect
ELSE
bounds := newBounds;
(* Keep the old depth, or get the old one *)
IF newDepth = 0 THEN
depth := updPort^.portPixMap^^.pixelSize
ELSE
depth := newDepth;
(* Get the old clut, or save new clut’s state and make it nonpurgeable *)
IF newColors = NIL THEN
colors := updPort^.portPixMap^^.pmTable
ELSE
BEGIN
savedState := HGetState(Handle(newColors));
HNoPurge(Handle(newColors));
colors := newColors;
END;
(* Calculate the number of bytes per row in the off-screen PixMap *)
/* Get rid of the old PixMap and its dependents */
DisposPtr( (**oldPixMap).baseAddr );
DisposeCTable( (**oldPixMap).pmTable ) ;
DisposHandle( (Handle)oldPixMap );
}
}
else
error = MemError();
}
/* Restore the given state of the color table */
if (colors != nil)
HSetState( (Handle)colors, savedState );
/* One Last Look Around The House Before We Go… */
if (error != noErr)
{
/* Some error occurred; dispose of everything we allocated */
if (newPixMap != nil)
{
if ((**newPixMap).pmTable)
DisposCTable( (**newPixMap).pmTable );
if ((**newPixMap).baseAddr)
DisposPtr ( (**newPixMap).baseAddr );
DisposHandle( (Handle)newPixMap );
}
}
return error;
}
UpdateOffScreen begins by checking the boundary rectangle, depth, or color table for emptiness, zero, or NIL, respectively. If any these satisfy that condition, then the existing characteristic is used. Next, the same sanity check that CreateOffScreen uses is done. If this sanity check succeeds, then a new PixMap is allocated, and then it’s initialized by the SetUpPixMap routine that’s given in Listing 2 which gives the new PixMap a new pixel image and its own copy of the color table. This new PixMap is installed into the CGrafPort after saving the reference to the old PixMap. Then, the portRect, visRgn, and clipRgn of the CGrafPort are set to the new boundary rectangle, as is the gdRect of the GDevice. The gdType of the GDevice is set either for the indexed-color or direct-color model, the gdPMap is set to the new PixMap, and the device attributes are set according to the pixel depth. Details about the settings for the CGrafPort and GDevice are in “Building the CGrafPort” and “Building the GDevice,” respectively, earlier in this Note.
At this point, the off-screen graphics environment is ready with its new characteristics, but it has garbage for an image because nothing has been drawn into it yet. The old PixMap, pixel image, and color table are still around, so _CopyBits transfers the old image into the altered graphics environment. _CopyBits handles the mapping from the old image’s characteristics to the new characteristics, so the altered graphics environment gets the best possible representation of the old image according to its new characteristics.
Changing the Off-Screen Color Table
Sometimes, it’s useful to change some or all of the colors in an off-screen color table, or to replace the off-screen color table with another one, so that the existing image in an indexed-color graphics environment appears with new colors. For example, if you had an off-screen image of a blue car and wanted to see what it looked like in green, you could change all of the shades of blue in the off-screen color table to green, and then _CopyBits the image to the screen. Notice that this is different from calling the UpdateOffScreen routine in the previous section with a different color table. That routine tries to reproduce the colors from the original image as best it can in the new set of colors. This section discusses the case in which you want the image’s colors to change.
The most obvious part of doing this is simply to get the color table from the off-screen pixel map’s pmTable field and modify the entries, or to dispose of the off-screen graphics environment’s current color table and assign the new one to it. There’s one more step to complete the process though. The discussion about GDevice records in “The Building Blocks” in this Note discusses inverse tables and how they go hand-in-hand with color tables. If you alter or replace the color table, you have to make sure that the inverse table of the off-screen drawing environment is rebuilt according to the new colors because Color QuickDraw uses that inverse table to know what pixel values to use for the specified color. You don’t have to rebuild the inverse table explicitly as long as you tell Color QuickDraw that the color table changed. To do this, all you have to do is make sure that the ctSeed of the changed or altered color table is set to a new value. And to do this, you can simply call _CTabChanged, which is documented on page 17-26 of the “Color QuickDraw” chapter of Inside Macintosh Volume VI. _CTabChanged is available beginning with 32-Bit QuickDraw and it’s available in system software version 7.0. If this routine isn’t available, then you can still tell Color QuickDraw that the color table has been changed by calling _GetCTSeed and assigning its result directly to your new color table’s ctSeed field.
The next time you draw into this off-screen drawing environment, Color QuickDraw checks the ctSeed of the environment’s color table against the iTabSeed of the inverse table of the environment’s GDevice. Because you changed the ctSeed of the color table either through _CTabChanged or _GetCTSeed, these two seeds are different so Color QuickDraw automatically rebuilds the inverse table of the current GDevice and then it copies the ctSeed of the color table to the iTabSeed of the rebuilt inverse table. Then drawing continues normally.
Follow That Screen!
One common need of off-screen graphics environments is that they have a depth and color table that matches a screen. The CreateOffScreen routine requires a color table for indexed-color environments, and a pixel depth. Because there can be more than one screen attached to a Macintosh system, you have to decide which screen’s depth and color table you should use. Typically, the depth and color table of the deepest screen that contains the area that you’re interested in (probably the area of a window) is used. Another option is to use the depth and color table of the screen that has the largest area of intersection with the area that you’re interested in. To find the depth and color table of the screen on which you want to base an off-screen graphics environment, you must use the list of graphics devices for all screens which is maintained by the system. Every GDevice record for a screen has a handle to that screen’s PixMap, and you can find the screen’s depth and color table there.
Listing 8 shows a routine called CreateScreenOffScreen which creates an off-screen graphics environment that has the depth and color table of a selected screen. The first parameter, bounds, specifies the rectangular part of the screen area in which you’re interested in global coordinates. The screenOption parameter specifies how you want the screen to be chosen. If you pass kDeepestScreen in this parameter, CreateScreenOffScreen creates the new off-screen graphics environment with the depth and color table of the deepest screen that intersects the bounds rectangle. If you instead pass kLargestScreenArea, then the new off-screen graphics environment is created with the depth and color table of the screen with the largest area of intersection with the bounds rectangle.
MPW Pascal Listing 8
TYPE
ScreenOpt = (kDeepestScreen, kLargestAreaScreen);
FUNCTION CreateScreenOffScreen(
bounds: Rect; {Global rectangle of part of screen to save}
screenOption: ScreenOpt; {Use deepest or largest intersection area screen?}
VAR retPort: CGrafPtr; {Returns a pointer to the new CGrafPort}
VAR retGDevice: GDHandle {Returns a handle to the new GDevice}
): OSErr;
VAR
baseGDevice: GDHandle; {GDevice to base off-screen on}
aGDevice: GDHandle; {Handle to each GDevice in the GDevice list}
basePixMap: PixMapHandle; {baseGDevice’s PixMap}
maxArea: LongInt; {Largest intersection area found}
area: LongInt; {Area of rectangle of intersection}
commonRect: Rect; {Rectangle of intersection}
normalBounds: Rect; {bounds rectangle normalized to (0, 0)}
error: Integer; {Error code}
BEGIN
error := noErr;
(* Different screen options require different algorithms *)
IF screenOption = kDeepestScreen THEN
(* Graphics Devices Manager tells us the deepest intersecting screen *)
baseGDevice := GetMaxDevice(bounds)
ELSE IF screenOption = kLargestAreaScreen THEN
BEGIN
(* Get a handle to the first GDevice in the GDevice list *)
aGDevice := GetDeviceList;
(* Keep looping until all GDevices have been checked *)
maxArea := 0;
baseGDevice := NIL;
WHILE aGDevice <> NIL DO
BEGIN
(* Check to see whether screen rectangle and bounds intersect *)
IF SectRect(aGDevice^^.gdRect, bounds, commonRect) THEN
BEGIN
(* Calculate area of intersection *)
area := LongInt(commonRect.bottom - commonRect.top) *
LongInt(commonRect.right - commonRect.left);
(* Keep track of largest area of intersection so far *)
IF area > maxArea THEN
BEGIN
maxArea := area;
baseGDevice := aGDevice;
END;
END;
(* Go to the next GDevice in the GDevice list *)
aGDevice := GetNextDevice(aGDevice);
END;
END
ELSE
error := paramErr;
(* If no screens intersect the bounds, baseDevice is NIL *)
Finding the deepest screen that intersects an on-screen area is trivially easy because there’s a Graphics Devices Manager routine that finds it called _GetMaxDevice which is documented on page 21-22 of the “Graphics Devices Manager” chapter of Inside Macintosh Volume VI. The rectangle in global coordinates of the screen area you’re interested in is passed to _GetMaxDevice, and it returns a handle to the deepest screen that intersects that area, even if the area of intersection is as small as one pixel. If no screens intersect that area, then _GetMaxDevice returns NIL.
Finding the GDevice of the screen that has the maximum area of intersection with the screen area you’re interested in isn’t quite so easy because there’s no single Graphics Devices Manager routine to find this GDevice; you have to search the GDevice list yourself. You can get a handle to the first GDevice in the list by calling _GetDeviceList, and you can get a handle to each successive GDevice by calling _GetNextDevice. _GetDeviceList is documented on pages 21-21 through 21-22 of the “Graphics Devices Manager” chapter of Inside Macintosh Volume VI, and _GetNextDevice is documented on page 21-22 of the same chapter. For each GDevice in the list, the area of intersection between the bounds and the gdRect of the GDevice is calculated. If the calculated area is the largest area of intersection found so far, then that area and the GDevice of that screen are remembered.
Once a winning GDevice has been chosen, either by being the deepest intersecting GDevice or the GDevice with the largest intersecting area, then CreateOffScreen routine is called with the pixel depth and color table of the PixMap of the GDevice, and the bounds rectangle normalized so that its top-left coordinate has the coordinates (0, 0). CreateOffScreen returns with the new off-screen graphics environment, and CreateScreenOffScreen returns this to the caller.
Choosing Your Off-Screen Memory
The CreateOffScreen routine in Listing 1 creates an off-screen graphics environment with its pixel image allocated as a nonrelocatable block in the application’s heap. But this isn’t the only way that the pixel image can be allocated. Pixel images can be big, and big blocks of nonrelocatable memory in your heap can be expensive in terms of performance, and they can cause a bad case of heap fragmentation. Why not put the pixel image in a relocatable block of memory instead? If there isn’t much free memory in your heap and if MultiFinder or system software version 7.0 is running, there’s memory that’s not being used by any open applications, called temporary memory (formerly called MultiFinder temporary memory). Why not use this area of memory for the pixel image? Some people have NuBus cards with plenty of memory on them. Why not move the pixel image out of the heaps altogether and instead use NuBus memory for the pixel image? All of these things can be done with simple modifications to what’s been discussed in this Note, and these modifications are discussed in the next few paragraphs.
How can pixel images be relocatable? After all, pixel images are referred to only by the baseAddr field of a PixMap, and the baseAddr is a pointer, not a handle. It’s true that while QuickDraw is being used to draw into a graphics environment, the pixel image had better not move or else QuickDraw will start drawing over the area of memory that the pixel image used to be rather than where it is. But if QuickDraw isn’t doing anything with the graphics environment, then it doesn’t care what happens to the pixel image as long as the baseAddr points to it once QuickDraw starts drawing into the graphics environment. This implies a strategy: allocate the pixel image as a relocatable block and let it float in the heap; when QuickDraw is about to to draw into the graphics environment or to copy from it, lock the pixel image and copy its master pointer into the baseAddr field of the PixMap; when the drawing or copying is finished, unlock the pixel image. There are many ways to implement this, and Listing 9 shows a code fragment for one very simple method.
MPW Pascal Listing 9
...
(* Allocate the pixel image; use long multiplication to avoid overflow *)
Listing 9 starts with a code fragment from the SetUpPixMap routine that’s modified so that it allocates a new handle for the off-screen pixel image instead of a new pointer. This handle is saved in the baseAddr field for now. When you’re about to draw into the off-screen graphics environment or to copy from it, the LockOffScreen routine in Listing 9 should be called with a pointer to the off-screen graphics environment’s CGrafPort as the parameter. It takes the handle to the pixel image from the baseAddr field of the off-screen graphics environment’s PixMap and passes it to _HLock which makes sure the pixel image can’t move in the heap. Then, the pixel image’s handle is dereferenced to get the master pointer to the pixel image, and this master pointer is copied into the baseAddr field. Now, QuickDraw can draw into or copy from the off-screen graphics environment.
When you’re finished drawing into the off-screen graphics environment, the pixel image should be unlocked, and the UnlockOffScreen routine in Listing 9 does this. The baseAddr field of the PixMap holds the pixel image’s master pointer, so this is passed to _RecoverHandle to get the pixel image’s handle. This handle is passed to _HUnlock to let the pixel image float in the heap again, and then this handle is saved in the baseAddr field.
One potentially useful addition to the LockOffScreen routine would be a call to _MoveHHi just before the call to _HLock. This helps reduce heap fragmentation while the pixel image is locked by moving it up as high in the heap as possible before locking it, allowing the other relocatable blocks to move without tripping over it. You have to be careful with _MoveHHi though because it not only moves the handle as high in the heap as possible, it moves other relocatable blocks out of the top of the heap to make room for the handle. This could involve moving huge amounts of memory, and it’s not unusual for _MoveHHi to take several seconds to do this.
How do you make an off-screen graphics environment that uses temporary memory for the pixel image? Temporary memory is allocated as handles, so there’s almost no difference between using temporary memory and using relocatable blocks in your own heap in the way that Listing 9 shows. All you have to do is replace the calls to _NewHandle, _HLock, and _HUnlock with calls to _TempNewHandle, _TempHLock, and _TempHUnlock. If temporary memory handles are real, then you don’t even have to replace the _HLock and _HUnlock calls—they work properly with temporary memory handles that are real.You can tell whether temporary memory handles are real or not by calling _Gestalt with the gestaltOSAttr selector. If the gestaltRealTempMemory bit is set, then all temporary memory handles are real. See the sections “About Temporary Memory” and “Using Temporary Memory” of Inside Macintosh Volume VI, pages 28-33 through 28-40.
How do you make an off-screen graphics environment that stores the pixel image on a NuBus memory card? The Macintosh Memory Manager doesn’t keep track of heaps on NuBus memory cards so it can’t be used to allocate memory on those cards, but if applications can use that card’s memory at will, then an application can set up the off-screen graphics environment with its pixel image in the NuBus card’s memory simply by setting the address of the card’s memory in the baseAddr field of the off-screen graphics environment’s PixMap instead of allocating anything.
If your NuBus memory card doesn’t require 32-bit addressing mode to access its memory, then setting the baseAddr to the address of the NuBus card’s memory is all you have to do. Some NuBus memory cards require its memory to be accessed in 32-bit addressing mode. Without 32-Bit QuickDraw, these memory cards can’t be used for storing the pixel image of an off-screen graphics environment because Color QuickDraw without 32-Bit QuickDraw always reads and writes pixel images in 24-bit addressing mode regardless of whether the pixel image is in main memory, on a NuBus video card, or on a NuBus memory card. With 32-Bit QuickDraw, Color QuickDraw automatically switches to 32-bit addressing mode before reading or writing a pixel image that’s on a video card. It won’t know to switch to 32-bit addressing mode if your off-screen graphics environment uses a pixel image on a NuBus memory card that’s not a video card, but you can tell it to make this switch by setting bit 2 of the pmVersion field of the PixMap for the off-screen graphics environment. This is normally done by logically ORing the pmVersion field with the predefined constant baseAddr32. See “About 32-Bit Addressing” in Issue 6 of develop, page 36, for more details about how QuickDraw handles addressing modes.
The GWorld Factor
In May 1989, 32-Bit QuickDraw was introduced as an extension to the system. While it had a lot of new features, the GWorld mechanism was the one that made the big news. GWorlds are off-screen graphics environments that you can have the system put together in one call. There’s no need for routines like CreateOffScreen, SetUpPixMap, or CreateGDevice—all of the off-screen graphics environment is set up with _NewGWorld. You can change most of its characteristics with _UpdateGWorld, set the current off-screen graphics environment with _SetGWorld, and get rid of the off-screen graphics environment with _DisposeGWorld. All the GWorld routines are described in the “Graphics Devices Manager” chapter of Inside Macintosh Volume VI. As an example, Listing 10 shows the same routine as the ExerciseOffScreen routine that’s shown in Listing 5, but Listing 10 uses GWorlds rather than the do-it-yourself routines that are defined in this Note.
MPW Pascal Listing 10
PROCEDURE ExerciseOffScreen;
CONST
kOffDepth = 8; {Number of bits per pixel in off-screen environment}
rGrayClut = 1600; {Resource ID of gray-scale clut}
rColorClut = 1601; {Resource ID of full-color clut}
VAR
grayPort: GWorldPtr; {Graphics environment for gray off screen}
colorPort: GWorldPtr; {Graphics environment for color off screen}
savedPort: GrafPtr; {Pointer to the saved graphics environment}
savedDevice: GDHandle; {Handle to the saved color environment}
offColors: CTabHandle; {Colors for off-screen environments}
offRect: Rect; {Rectangle of off-screen environments}
circleRect: Rect; {Rectangles for circle-drawing}
count: Integer; {Generic counter}
aColor: RGBColor; {Color used for drawing off-screen}
error: OSErr; {Error return from off-screen creation}
BEGIN
(* Set up the rectangle for the off-screen graphics environments *)
SetRect(offRect, 0, 0, 256, 256);
(* Get the color table for the gray off-screen graphics environment *)
offColors := GetCTable(rGrayClut);
(* Create the gray off-screen graphics environment *)
/* Copy the color off-screen environment to the current port */
SetGWorld( savedPort, savedDevice );
CopyBits( &((GrafPtr)colorPort)->portBits,
&((GrafPtr)savedPort)->portBits,
&colorPort->portRect,
&savedPort->portRect,
srcCopy, nil );
/* Dispose of the off-screen graphics environments */
DisposeGWorld( grayPort );
DisposeGWorld( colorPort );
}
}
}
_NewGWorld creates an off-screen graphics environment by creating a CGrafPort, PixMap, and GDevice—the same structures that you normally put together when you make an off-screen graphics environment yourself. In this aspect, and in fact in most aspects, there’s nothing magical about GWorlds. Do GWorlds make the CreateOffScreen, DisposeOffScreen, and their dependents useless? That depends on what your needs are. What follows are a few issues about off-screen drawing and how that determines whether you use your own routines, such as CreateOffScreen, to create and maintain off-screen graphics environments or whether you use GWorlds for the same purpose.
I Want the Best Performance!
As mentioned in the last paragraph, there’s nothing magical about GWorlds in most aspects. In one major aspect, there certainly is: the version of Color QuickDraw that runs with the 8•24 GC video card’s acceleration on knows about GWorlds and can cache their CGrafPort, PixMap, GDevice, inverse table, color table, and pixel image on the 8•24 GC card if there’s enough memory on it. When this is done, QuickDraw operations on the GWorld can be much faster than they’d normally be because the image data can stay in the card’s memory where the fast microprocessor is, and image data doesn’t have to move across NuBus in transfer operations between the GWorld and the screen. Additionally, these operations are executed asynchronously which increases the overall speed of your programs. For details about how the 8•24 GC card and GC QuickDraw work, see Guillermo Ortiz’s article, “Macintosh Display Card 8•24 GC: The Naked Truth,” in Issue 5 of develop.
8•24 GC QuickDraw doesn’t know about the off-screen graphics environments that you create, so it doesn’t cache its structures. All QuickDraw commands that move image data between the off-screen graphics environment and the screen have to move the data across NuBus, and that slows down the operation in comparison to keeping all the image data on the card.
If you want the highest possible drawing and copying performance with the 8•24 GC card, you must use GWorlds for your off-screen graphics environments.
I Want to Use a NuBus Memory Card for My GWorld’s Off-Screen Pixel Image
One common desire is to use a NuBus memory card to hold a pixel image. Because GWorlds are so easy to set up, and because GWorlds have all the same parts that you can make for an off-screen graphics environment, it’s tempting to make a GWorld and then point the baseAddr of the GWorld’s PixMap at the NuBus card’s memory. But GWorlds are designed to be fairly atomic structures, so they can’t be changed in this way. You can change a GWorld’s dimensions, depth, and color table because there’s a routine (_UpdateGWorld) that is designed to change these things, but you can’t change the pixel image without risking future compatibility.
If you want to have an off-screen graphics environment use a NuBus video card to store the pixel image, you should set up your own off-screen graphics environment rather than use GWorlds. This is covered earlier in this Note in “Choosing Your Off-Screen Memory.”
I Want My Program to Work on All System Software Releases
GWorlds have been around since 32-Bit QuickDraw was released (while system software version 6.0.3 was current). Until system software version 7.0, 32-Bit QuickDraw was an optional part of the system, so you aren’t guaranteed use of GWorlds even under recent system software releases. Obviously, if GWorlds aren’t available and your program still has to work with off-screen graphics environments, then there’s no choice but to use your own routines for creating, maintaining, and disposing of off-screen graphics environments. What’s usually done in these cases is to check via _Gestalt whether GWorlds are available or not. If they aren’t, then you create your off-screen graphics environment with your own routines. If they are, then you can use GWorlds without having to take up memory with your code for creating off-screen graphics environments yourself.
Are We There Yet?
Reliable, understandable, and maintainable off-screen drawing routines means not taking short-cuts. The most common problems that people run into with off-screen drawing routines is the appearance of strange colors and the gradual degradation of reliability as the program does more off-screen drawing. Building an off-screen graphics environment out of a CGrafPort, GDevice, and PixMap or by using GWorlds, combined with an understanding of how Color QuickDraw uses off-screen graphics environments, helps get rid of these problems. Hopefully, this Note helps you understand these things so that you can get better programs out the door faster.
Further Reference:
• Apple Computer, Inc., Inside Macintosh Volume I, Addison-Wesley, Reading, MA, 1985
• Apple Computer, Inc., Inside Macintosh Volume V, Addison-Wesley, Reading, MA, 1988.
• Apple Computer, Inc., Inside Macintosh Volume VI, Addison-Wesley, Reading, MA, 1991.
• Knaster, S., Macintosh Programming Secrets, Addison-Wesley, Reading, MA, 1988.
• Leak, B., “Realistic Color For Real-World Applications,” develop, January 1990, 4-21.
• Ortiz, G., “Braving Offscreen GWorlds,” develop, January 1990, 28-40.
• Ortiz, G., “Deaccelerated _CopyBits & 8•24 GC QuickDraw,” Macintosh Technical Note #289, January 1991.
• Ortiz, G., “Macintosh Display Card 8•24 GC: The Naked Truth,” develop, July 1990, 332-347.
• Othmer, K., “QuickDraw’s CopyBits Procedure: Better Than Ever in System 7.0,” develop, Spring 1991, 23-42.
• Tanaka, F., “Of Time and Space and _CopyBits,” Macintosh Technical Note #277, June 1990.
• Zap, J., F. Tanaka, J. Friedlander, and G. Jernigan, “Drawing Into an Off-Screen Bitmap,” Macintosh Technical Note #41, June 1990.
NuBus is a trademark of Texas Instruments.
QD 14 - QuickDraw’s Internal Picture Definition
QuickDraw
Revised by: Rick Blair November 1986
March 1988
Written by: Ginger Jenigan April 1985
This technical note describes the internal format of the QuickDraw picture data structure. This revision corrects some errors in the opcode descriptions and provides some examples.
This technical note describes the internal definition of the QuickDraw picture. The information given here only applies to QuickDraw picture format version 1.0 (which is always created by Macintoshes without Color QuickDraw). Picture format version 2.0 is documented in the Color QuickDraw chapter of Inside Macintosh. This information should not be used to write your own picture bottleneck procedures; if we add new objects to the picture definition, your program will not be able to operate on pictures created using standard QuickDraw. Your program will not know the size of the new objects and will, therefore, not be able to proceed past the new objects. (What this ultimately means is that you can’t process a new picture with an old bottleneck proc.)
Terms
An opcode is a number that DrawPicture uses to determine what object to draw or what mode to change for subsequent drawing. The following list gives the opcode, the name of the object (or mode), the associated data, and the total size of the opcode and data. To better interpret the sizes, please refer to page I-91 of the Using Assembly Language chapter of Inside Macintosh. For types not described there, here is a quick list:
opcode byte
mode word
point 4 bytes
0..255 byte
–128..127 signed byte
rect 8 bytes
poly 10+ bytes (starts with word size for poly (incl. size word)
region 10+ bytes (starts with word size for region (incl. size word)
fixed point long
pattern 8 bytes
rowbytes word (always even)
bit data rowbytes * (bounds.bottom - bounds.top) bytes
Each picture definition begins with a picsize (word), then a picframe (rect), and then the picture definition, which consists of a combination of the following opcodes:
Opcode Name Additional Data Total Size (bytes)
00 NOP none 1
01 clipRgn rgn 1+rgn
02 bkPat pattern 9
03 txFont font (word) 3
04 txFace face (byte) 2
05 txMode mode (word) 3
06 spExtra extra (fixed point) 5
07 pnSize pnSize (point) 5
08 pnMode mode (word) 3
09 pnPat pattern 9
0A thePat pattern 9
0B ovSize point 5
0C origin dh, dv (words) 5
0D txSize size (word) 3
0E fgColor color (long) 5
0F bkColor color (long) 5
10 txRatio numer (point), denom (point) 9
11 picVersion version (byte) 2
20 line pnLoc ( point ), newPt ( point ) 9
21 line from newPt ( point ) 5
22 short line pnLoc ( point ); dh, dv (-128..127) 7
23 short line from dh, dv (-128..127) 3
28 long text txLoc ( point ), count (0..255), text 6+text
29 DH text dh (0..255), count (0..255), text 3+text
2A DV text dv (0..255), count (0..255), text 3+text
2B DHDV text dh, dv (0..255), count (0..255), text 4+text
30 frameRect rect 9
31 paintRect rect 9
32 eraseRect rect 9
33 invertRect rect 9
34 fillRect rect 9
38 frameSameRect rect 1
39 paintSameRect rect 1
3A eraseSameRect rect 1
3B invertSameRect rect 1
3C fillSameRect rect 1
40 frameRRect rect ( ovalwidth, height; see 1, below ) 9
41 paintRRect rect ( ovalwidth, height; see 1, below ) 9
42 eraseRRect rect ( ovalwidth, height; see 1, below ) 9
43 invertRRect rect ( ovalwidth, height; see 1, below ) 9
44 fillRRect rect ( ovalwidth, height; see 1, below ) 9
48 frameSameRRect rect 1
49 paintSameRRect rect 1
Opcode Name Additional Data Total Size (bytes)
4A eraseSameRRect rect 1
4B invertSameRRect rect 1
4C fillSameRRect rect 1
50 frameOval rect 9
51 paintOval rect 9
52 eraseOval rect 9
53 invertOval rect 9
54 fillOval rect 9
58 frameSameOval rect 1
59 paintSameOval rect 1
5A eraseSameOval rect 1
5B invertSameOval rect 1
5C fillSameOval rect 1
60 frameArc rect, startAngle, arcAngle 13
61 paintArc rect, startAngle, arcAngle 13
62 eraseArc rect, startAngle, arcAngle 13
63 invertArc rect, startAngle, arcAngle 13
64 fillArc rect, startAngle, arcAngle 13
68 frameSameArc startAngle, arcAngle 5
69 paintSameArc startAngle, arcAngle 5
6A eraseSameArc startAngle, arcAngle 5
6B invertSameArc startAngle, arcAngle 5
6C fillSameArc startAngle, arcAngle 5
70 framePoly poly 1+poly
71 paintPoly poly 1+poly
72 erasePoly poly 1+poly
73 invertPoly poly 1+poly
74 fillPoly poly 1+poly
78 frameSamePoly (not yet implemented—same as 70, etc.) 1
79 paintSamePoly (not yet implemented) 1
7A eraseSamePoly (not yet implemented) 1
7B invertSamePoly (not yet implemented) 1
7C fillSamePoly (not yet implemented) 1
80 frameRgn rgn 1+rgn
81 paintRgn rgn 1+rgn
82 eraseRgn rgn 1+rgn
83 invertRgn rgn 1+rgn
84 fillRgn rgn 1+rgn
88 frameSameRgn (not yet implemented—same as 80, etc.) 1
maskRgn, packed bitData for each row packed bitData
A0 shortComment kind(word) 3
A1 longComment kind(word), size(word), data 5+data
FF EndOfPicture none 1
Notes
Rounded-corner rectangles use the setting of the ovSize point (see opcode $0B, above).
OpenPicture and DrawPicture set up a default set of port characteristics when they start. When drawing occurs, if the user’s settings don’t match the defaults, mode opcodes are generated. This is why there is usually a clipRgn code after the picVersion: the default clip region is an empty rectangle.
The only savings that the “same” opcodes achieve under the current implementation is for rectangles. DrawPicture keeps track of the last rectangle used and if a “same” opcode is encountered that requests a rectangle, the last rect. will be used (and no rectangle will appear in the opcode’s data).
This last section contains some Pascal program fragments that generate pictures. Each section starts out with the picture itself (yes, they’re dull) followed by the code to create and draw it, and concludes with a commented hex dump of the picture.
{variables used in all examples}
VAR
err: OSErr;
ph: PicHandle;
h: Handle;
r: Rect;
smallr: Rect;
orgr: Rect;
pstate: PenState; {are they in the Rose Bowl, or the state pen?}
90 0002 000A 0014 000F 001C {BitsRect rowbytes bounds (note that bounds is wider than smallr)}
000A 0014 000F 0019 {srcRect}
0000 0000 0014 001E {dstRect}
00 06 {mode=notSrcXor}
0000 0000 0000 0000 0000 {5 rows of empty bitmap (we copied from a
still-blank window)}
FF {fin}
Further Reference:
• QuickDraw
• Color QuickDraw
• Using Assembly Language
• Technical Note #59—Pictures and Clip Regions
QD 15 - RowBytes Revealed II
QuickDraw
Written by:Bill Guschwan May 1993
This Technical Note discusses the maximum rowBytes value for a pixMap.
Topics
• What is the largest value of rowBytes?
• Why does it have a limit?
• How do you increase the limit?
Introduction
This technical note concerns applications which create and read very large pixMaps. The rowBytes field defines the limits of the largest pixMap. For applications which use 32-Bit QuickDraw, this limit is well-defined: 0x3FFE. However, a few applications want to go beyond this limit, and under some extremely controlled situations, this limit can be extended to 0x7FFE. This note explains why the limit exists, and proposes a few difficult methods to exceed this limit. Along the way, proper parameter passing for CopyBits is discussed and a few debugging tips are thrown in.
Largest size of rowBytes of a pixMap
rowBytes is important because it defines the size of a pixMap. rowBytes had a largest size of 0x1FFE up through Color QuickDraw. The top three bits were reserved.
Version 1.0 of 32-Bit QuickDraw extended that limit to 0x3FFE: only the top two bits are reserved. QuickDraw uses the two bits for identification purposes. The top bit distinguishes between a pixMap and a bitMap. If the top bit of rowBytes is set, then QuickDraw knows the structure is a pixMap. The second highest bit is used by CopyBits, CopyMask, CopyDeepMask, SeedCFill, and CalcCMask to distinguish between their bitMap parameters. The implications of this identification scheme are fully discussed below.
3 Types of BitMap Parameters
CopyBits, CopyMask, CopyDeepMask, SeedCFill, and CalcCMask are routines which take bitMaps as their first two parameters. For historical and compatibility reasons, three types of parameters can be passed in: bitMap, pixMaps and the portBits field of a cGrafPort.
For the purposes of this note, I will focus on the CopyBits call, though my discussion will apply to the other four routines. The behavior of these five calls is identical for the bitMap parameters.
The BitMap
The bitMap parameter is actually a pointer to a bitMap. In Pascal, the pointer is implicit, since a bitMap structure is greater than 4 bytes in size and the Pascal compiler creates a pointer for any data structure greater than 4 bytes.
In C:
pascal void CopyBits(const BitMap *srcBits,const BitMap *dstBits,const Rect
*srcRect, const Rect *dstRect,short mode,RgnHandle maskRgn) = 0xA8EC;
With Color QuickDraw, CopyBits accepts pixMaps as BitMap parameters. This support, however, does not come without a cost. CopyBits needs a method to distinguish between the two parameters. As mentioned above, the top bit of rowBytes distinguishes between pixMaps and bitMaps. While this bit allows pixMaps to be passed in to CopyBits, the size of rowBytes is diminished. All design choices have trade-offs.
The portBits of a CGrafPort
In designing Color QuickDraw, certain rules were set up to provide compatibility with the new features. Here was one rule: you should be able to pass a portPixMap field to CopyBits just as you would pass a portBits field. Unfortunately, portPixMap is a handle whereas portBits is a BitMap. Tricky type-casting, however, allows one to pass in a cGrafPort's portPixMap field, as the following examples show. You must coerce the cGrafPtr in to a grafPtr in order to use the portBits field.
In C:
CGrafPtr colorPort; /* Graphics environment for color off screen */
GrafPtr savedPort; /* Pointer to the saved graphics environment */
Typecasting is not the only trickery involved here. CopyBits is faced with a major headache if you think about it. PortPixMap is a handle, and the parameters of CopyBits expect a pointer to a pixMap. To solve this, CopyBits has a little algorithm in it which dereferences the pointer twice if you pass in a portBits. To identify the type of pointer it is getting, CopyBits looks at the top two bits of the rowBytes field. As mentioned above, the top bit distinguishes between a pixMap and a bitMap. The next bit tells CopyBits if the pixMap is part of a cGrafPort or not (see Fig. 1). If the two bits are set, then CopyBits knows it is being passed a pixMapHandle, and it will perform the dereference.
Figure 1. CopyBit's BitMap parameters
Figure 1. displays three types of CopyBit's BitMap parameters. Each points to a either a bitMap, pixMap, or the portPixMap field in a cGrafPort. After 4 bytes, the top two bits of the fifth byte identifies the pointer.
Why Large PixMaps Crash Apps
As you can see, the top two bits of rowBytes have specific functions. The highest bit distinguishes between bitMaps and pixMaps. The second highest bit identifies the type of BitMap parameter. If it is set, a dereference is applied; if not, nothing happens to the pixMap. If your pixMap uses the second highest bit of rowBytes and you pass it into a QuickDraw application, it will think it is part of a cGrafPort, and will perform a handle dereference on your baseAddr. The first dereference will get to video memory, but the second dereference will be on whatever random video data happens to be there. Your application will land up in Never-Never land.
If you create pictures which can be redistributed, leave the top two bits of rowBytes alone. Below, I will identify one method of going around this limit, but it will only work in specific situations. If you read pictures, look below for reading pictures which go around this limit.
Identifying CGrafPorts and GWorlds in a Debugger
You'll notice in Figure 1 that the portVersion field of a cGrafPort coincides with the location of the rowBytes field of a grafPort. Remember, a cGrafPort has the same size as a grafPort. During debugging, you can use the same information which CopyBits uses to identify cGrafPorts.
If you use a grafPort template to display memory for an unknown grafPort, you can tell if it is a cGrafPort because the rowBytes will be equal to 0xC000. The 0xC corresponds to the two high bits being set in the portVersion field of a cGrafPort. Since these bits can not be set in a grafPort, you know you have a cGrafPort. In addition, if the bottom bit of the portVersion field is set, then it is a gWorld. Thus, if your rowBytes field has a value of 0xC001, then you know you have a gWorld.
Even or odd rowBytes?
Since the dawn of Macintosh, it has been said that rowBytes should be even because each row of a pixMap must contain an integral number of words. Actually, rowBytes has to be even because QuickDraw accesses bitmap data using word or long operands, and these generate address errors when it references an odd address on the 68000, which would happen if rowBytes is odd. The 68020 and later handle odd addresses fine, and so rowBytes can be odd. But, it is still recommended that rowBytes be even, because misaligned accesses incur a performance penalty.
Going Around The Limit Today
In the world today applications have a difficulty because they can either refuse to create pixMaps as big as users want or cause crashes by confusing CopyBits into dereferencing the base address of the pixMap if rowBytes exceeds the established limit of less than 0x4000. Some well-known image applications create such pixMaps with bad results. Reading large pixMaps causes the crash, but applications which create them are the ultimate culprit.
As far as a solution for the present, a possibility is to bypass the CopyBits dereferencing algorithm. You can call StdBits directly since it does not mind dealing with larger than legal rowBytes. The problem here is that the destination is implied and the application has to make sure that everything is alright. Also, if the destination spans multiple devices, the application has to divide the task , targeting each device at the time. See the DeviceLoop procedure in IM VI for ideas on this.
A second possibility is to patch CopyBits in situations where you know it can only be fed pixMaps. DrawPicture time is one example. You need to patch right before DrawPicture because you know a picture will contain only pixMaps. That is, you know CopyBits will not be passed portBits. If rowBytes is too big, then the application could split the job, banding the image vertically until the resulting rowBytes values fall within range. After the DrawPicture call, you will need to unpatch.
Going Around The Limit Tomorrow
All this is known by engineering and some future directions are already being studied, for example it is possible that a next release of QuickDraw will support pixMap with a rowBytes constant value indicating that the real rowBytes is contained in the planeBytes field instead; I am sure you can immediately think of cases where this is also going to cause problems but we think that the problems are less important than the limitation being overcome.
Conclusion
The limitations of rowBytes is becoming an increasingly painful thing, applications can easily create pixMaps (and PICTs) that exceed the limit of 0x4000. It is possible for an application to patch CopyBits in order to work around this limitation but the application writer has to decide what is appropriate for each set of conditions. Thus, rowBytes has traditionally been said to have a maximum value of 0x3FFE. But, if your application avoids the use of CopyBits, CopyMask, and CopyDeepMask, then you can use a rowBytes value of 0x7FFF without harm. However, those situations are rare, and, for all practical matters, the limit of rowBytes is 0x3FFE.
Further Reference:
• Inside Macintosh, Volume I, QuickDraw
• Inside Macintosh, Volume V & VI, Color QuickDraw
• d e v e l o p 1, "Realistic Color For Real-World Applications"
QD 16 - 8•24 GC QuickDraw and Deaccelerated CopyBits
QuickDraw
Written by: Guillermo A. Ortiz February 1991
This Technical Note discusses conditions that may cause _CopyBits to slow down when QuickDraw acceleration is on via the Apple 8•24 GC Display Card.
Introduction
When a drawing call is issued, GC IPC (Interprocess Communication) takes control of the call and passes it to GC QuickDraw. After the normal port set up (which involves caching the port parameters if this is the first drawing call after the port was set), GC QuickDraw returns control to the application through the IPC and performs, in parallel, the drawing to its own monitor as well as any other monitors that may be affected by the operation. The application then continues its execution, probably issuing more drawing calls that get executed in the same asynchronous manner.
The result of this mode of operation is improved performance, since the application gets control back immediately after issuing the call and the GC QuickDraw moves video data to its own video buffer as well as that of other cards in a more rapid manner by using block transfers and without requiring any action by the main processor.
_CopyBits Conforms To The Same Scheme, Except…
_CopyBits conforms to the same operational scheme, but there are some instances in which GC QuickDraw cannot perform the call in parallel; in this cases it is even possible to suffer a performance loss, since the whole call may have to be completed before control is given back to the application and GC QuickDraw has to make calls and access data across the NuBus™.
The situations that compromise GC QuickDraw parallel operation are as follows:
• When the destination device has a SearchProc installed and the source color environment is different from the destination environment.
QuickDraw calls a SearchProc whenever the source and destination have different depths and when two indexed pixel maps have different color tables, even though their depths may be identical. When GC acceleration is enabled, these conditions cause the following two types of behavior, dependent upon the source pixel map:
• If the source is an indexed pixel map, then GC QuickDraw executes the part of the setup that involves calling the SearchProc, returns control to the main processor, then completes the call in parallel. The act of calling the SearchProc before returning control makes the call slower than when no SearchProc is involved, since parallel operation does not occur throughout the whole call.
• If the source is a direct RGB pixel map, then GC QuickDraw has to call the SearchProc for every pixel that is drawn, and the application does not regain control until after the call to _CopyBits has been completed.
• When the source or destination is offscreen and not created using a GWorld.
GC QuickDraw has no way to detect when an application is going to manipulate a pixel map it has created in memory, so if it has to draw to or copy from such a PixMap, GC QuickDraw has to complete the operation before returning control to the application.
This behavior is contrary to the case when using a GWorld for offscreen environments, since in the case of a GWorld, GC QuickDraw is alerted by the call to _GetPixBaseAddr that the application is getting ready to directly change the pixels. This is the reason why it is so important that applications call _GetPixBaseAddr every time they are about to manipulate a GWorld pixel map directly.
• When the source PixMap has a color table that uses indexes that refer to a palette.
QuickDraw now allows a color table to have indexes that point to entries in the palette associated with the destination window; when bit 14 in the ctFlags field is set, the value fields in the color table are treated as palette entries. When such a PixMap is the source for _CopyBits, then GC QuickDraw has to make a number of calls to the Palette Manager as part of the setup before returning control and completing the call.
This case is similar to that of a indexed pixel map when a SearchProc is involved; therefore, it only implies a partial loss of parallelism; it is good to keep in mind that this case can only occur when the source PixMap is indexed.
Further Reference:
• Inside Macintosh, Volumes V & VI, Color QuickDraw
• d e v e l o p, “Macintosh Display Card 8•24 GC: The Naked Truth,” July 1990.
• Technical Note #275, 32-Bit QuickDraw: Version 1.2 Features
• Developer Notes for the Macintosh Display Cards 4•8, 8•24 and 8•24 GC (APDA, M085TLL/A)
NuBus is a trademark of Texas Instruments.
QD 17 - Drawing Icons
QuickDraw
Written by: Jim Friedlander October 1985
Using resources of type ICON allows drawing of icons in srcOr mode. Using resources of type ICN# allows for more variety when drawing icons.
There are two different kinds of resources that contain icons: ICON and ICN#. An ICON is a 32 by 32 bit image of an icon and can be drawn using the following Toolbox Utilities calls:
MyIconHndl:= GetIcon(iconID);
PlotIcon(destRect,iconID);
While very convenient, this method only allows the drawing of icons in SrcOr mode (as in the MiniFinder). The Finder uses resources of type ICN# to draw icons on the desktop. Because the Finder uses ICN#s, it can draw icons in a variety of ways.
An ICN# resource is a list of 32 by 32 bit images that are grouped together. Common convention has been to group two 32 by 32 bit images together in each ICN#. The first image is the actual icon, the second image is the mask for the icon. To get a handle to an ICN#, we would use something like this:
TYPE
iListHndl = ^iListPtr;
iListPtr = ^iListStruct;
iListStruct = record
icon : packed array[0..31] of Longint;
mask : packed array[0..31] of Longint;
End; {iListStruct}
VAR
myILHndl : iListHndl; {handle to an ICN#}
iBitMap : BitMap; {BitMap for the icon}
mBitMap : BitMap; {BitMap for the mask}
MyILHndl:= iListHndl(GetResource('ICN#',iconID));
if MyILHndl = NIL then HandleError;
{and exit or whatever is appropriate}
Once we have a handle to the icons, we need to set up two bitMaps that we will be using later in CopyBits:
SetRect(icnRect,0,0,32,32); { define the icon's 'bounds'}
With iBitMap do Begin
baseAddr:= @MyILHndl^^.icon;
rowbytes:= 4; { 4 * 8 =32}
bounds:= icnRect;
End; {with}
With mBitMap do Begin
baseAddr:= @MyILHndl^^.mask;
rowbytes:= 4;
bounds:= icnRect;
End; {with}
Icons can represent desktop objects that are either selected or not. Folder and volume icons can either be open or not. The object (or the volume it is on) can either be online or offline. The Finder draws icons using all permutations of open, selected and online:
Drawing icons as non-open is basically the same for online and offline volumes. We need to punch a hole in the desktop for the icon. This is analogous to punching a hole in dough with an irregular shaped cookie-cutter. We can then sprinkle jimmies* all over the cookie and they will only stick in the area that we punched out (the mask). We do this by copyBitsing the mask onto the desktop (whatever pattern) to our destRect. For non-open, non-selected icons:
we use the SrcBic mode so that we punch a white hole:
we need to do a little more work. We need to XOR a ltGray pattern into the boundsRect of the icon. We will then punch the hole, draw the icon and then XOR out the ltgray pattern that does not fall inside the mask. So, to draw the icon as offline, non-open, non-selected we would:
GetPenState(OldPen); {save the pen state so we can restore it}
PenMode(patXor);
PenPat(ltGray);
PaintRect(destRect); {paint a ltGray background for icon}
Drawing the opened icons requires one less step. We don’’t have to CopyBits the icon in, we just use the mask. Online and offline icons are drawn the same way. To draw icons as open, selected:
we do the following:
GetPenState(OldPen); {save the pen state so we can restore it}
PenMode(patXor);
PenPat(dkGray); { the icon is selected, so we need dkGray }
PaintRect(destRect); { paint a dkGray background for icon}
PaintRect(destRect); {XOR out bits outside of the mask, leaving
the mask filled with dkGray}
SetPenState(OldPen); {restore the old pen state}
To draw icons as open, non-selected:
we just need to change one line from above. Instead of XORing with a dkGray pattern, we use a ltGray pattern:
PenPat(ltGray); {icon is non-selected, so we need ltGray}
These techniques will work on any background, window-white or desktop-gray and all patterns in between. Have fun.
* jimmies : little bits of chocolate
Further Reference:
• QuickDraw
• Toolbox Utilities
QD 18 - Drawing Icons the System 7 Way
QuickDraw
Revised by: Don Moccia and C.K. Haun <TR> October 1992
Written by: Jim Mensch and David Collins October 1991
This Technical Note describes how to utilize the built-in System 7 icon drawing utility. Use this information to better conform to the System 7 visual human interface.
Changes since May 1992: In this Note, we replaced the C and Pascal interface files and corrected the related text. So much text was tweaked that change bars are used only on code changes.
Introduction
With the introduction of System 7 for the Macintosh, Apple has defined a new look and feel for many screen elements that better utilize color. Among those redefined elements are the icons drawn by the Finder and other system components. Until now, Apple has not documented how to draw icons the way the Finder does in System 7.
This Technical Note discusses the icon toolkit calls that the Finder uses to draw and manipulate the screen icons. Two of the calls, PlotIconID and PlotCIconHandle, are the ones you will probably use the most since they simply deal with drawing single icons to the screen. Some parts of the toolbox require that an icon family handle be passed to them to allow the drawing of color icons. The icon toolkit provides calls that allow you to create, draw, and manipulate these handles.
The New 'ic' Type Resources
PlotIconID and PlotCIconHandle allow the use of standard CIcons as documented in Inside Macintosh Volume V. The PlotIconID call also permits the use of a new set of icon resources documented in Inside Macintosh Volume VI, Chapter 9. This new set is a collection of different icons, representing a single Finder object, into a family. Each member of the family has the same resource ID as the 'ICN#', and a resource type indicating the icon data it contains. Currently Apple has defined three sizes of icons and three bit depths for each size. The sizes are large (32 by 32 pixels), small (16 by 16 pixels), and mini (12 by 12 pixels). The bit depths are 1, 4, and 8. The actual resource types are defined as:
Large1BitMask = 'ICN#';
Large4BitData = 'icl4';
Large8BitData = 'icl8';
Small1BitMask = 'ics#';
Small4BitData = 'ics4';
Small8BitData = 'ics8';
Mini1BitMask = 'icm#';
Mini4BitData = 'icm4';
Mini8BitData = 'icm8';
The 1-bit-per-pixel member of each size also contains the mask data for all icons of that size (yes, this means that all your icons of a certain size must have the same mask). A 1-bit-per-pixel member must exist for each icon size that PlotIconID uses. The icon size used is determined by the size of the destination rectangle. If the destination rectangle is greater than 16 pixels on a side then the large icon will be used. If the rectangle is 13–16 pixels on both sides, the small icon will be used. If it is 12 or less on each side, the mini-icon will be used. The bit depth is determined by the device of the grafPort you plot into at drawing time. Be sure to create a color grafPort when you want to use color icons.
Icon Families (or Suites and Caches As the Tool Set Refers to Them)
An icon family is simply a collection of icon handles that contain up to one image of each bit depth and size for a given icon. The family can be fully populated (every possible size or depth available), or it can have only those icons that exist or are needed. By using families, you remove the need to determine which size or depth of icon to use when drawing into a given rectangle. Several system routines, the Notification Manager for example, can take an icon family handle when an icon is requested. This permits them to use the proper color icons if available. In the case of a sparsely populated icon family, when the proper icon is not available, the icon toolkit will pick a substitute to produce the best results.
An icon cache is a family that also has a ProcPtr and a refCon. The main difference between a cache and a family is that the elements of the cache’s array are sparsely populated. When using an icon cache, the system either will use the entry in the icon family portion of the cache or, if the desired element is empty, it will call the procedure pointed to by the ProcPtr and request the data for the icon. The procedure should have this interface:
FUNCTION IconGetter(theType: ResType;
yourDataPtr: Ptr): Handle;
This function should return either the icon data to be drawn or NIL to signify that this entry in the icon cache does not exist. Icon caches can be used with all icon family calls. A few extra calls are also available to manipulate icon caches.
Drawing Modes or Transforms
In addition to various sizes and bit depths, icons can be drawn with different modes or transforms. Transforms are analogous to certain Finder states for the icons. For example, the transform that you would use to show an icon of a disk that has been ejected is ttOffline. Here is a list of the available transforms:
ttNone = $0;
ttDisabled = $1;
ttOffline = $2;
ttOpen = $3;
ttSelected = $4000;
ttSelectedDisabled = (ttSelected + ttDisabled);
ttSelectedOffline = (ttSelected + ttOffline);
ttSelectedOpen = (ttSelected + ttOpen);
The actual appearance of the icon drawn by each transform type may vary with future system software, so you should always use the transform that best fits the state it represents in your application. This way you will be consistent with future changes to the look and feel of regular system icons. Note the ttSelected transform can be added to any of the other transform types.
There are also transforms that use the Finder label colors to color the icon. To determine the proper label for a file’s icon, you can check bits 1–3 of the fdFlags field in the file’s Finder info. (See the Finder Interface chapter in Inside Macintosh Volume VI for more information). These bits contain a number from 0 to 7. Simply add the corresponding ttLabel value to the transform that you give the call. The label values are defined like this:
ttLabel1 = $0100;
ttLabel2 = $0200;
ttLabel3 = $0300;
ttLabel4 = $0400;
ttLabel5 = $0500;
ttLabel6 = $0600;
ttLabel7 = $0700;
Alignment
Most icons do not fully fill their rectangle, and it is sometimes necessary to draw an icon relative to other data (like menu text). In these instances it is nice to be able to have the icon move in its rectangle so that it will be at a predictable location in the destination rectangle. When drawing an icon you can pass one of these standard alignments in the alignment parameter or you can add a vertical alignment to a horizontal alignment to create a composite alignment value.
And Now (Drum Roll Please) the Calls and What to Pass
Now that we have defined every major data type we can think of, here are the actual toolkit calls themselves. One word of caution: only the ForEachIconDo call protects the handle that is passed to it, so make your icon resources nonpurgeable.
Icon Family Calls
FUNCTION NewIconSuite(VAR theIconSuite: Handle): OSErr;
NewIconSuite returns an empty icon family handle with all members set to NIL.
FUNCTION AddIconToSuite(theIconData: Handle;
theSuite: Handle;
theType: ResType): OSErr;
This call will add the data in theIconData into the suite at the location reserved for theType of icon data. AddIconToSuite will replace any old data in that slot without disposing of it, so you may want to call GetIconFromSuite to obtain the old handle (if any) to dispose of it. This call will be used most often with the NewIconSuite call to fill the empty family after it’s created.
FUNCTION GetIconFromSuite(VAR theIconData: Handle;
theSuite: Handle;
theType: ResType): OSErr;
This call will return a handle to the pixel data of the family member of theSuite specified by theType. If you intend to dispose of this handle, be sure to call AddIconToSuite with a NIL handle to zero out the family entry.
FUNCTION ForEachIconDo(theSuite: Handle;
selector: IconSelectorValue;
action: IconAction;
yourDataPtr: Ptr): OSErr;
This routine will call your IconAction procedure (see below) for each icon in the family specified by selector and theSuite. The selector parameter is a bit-level flag that specifies which family members to operate on; they can be added together to create composite selectors that work on several different family members. The values for selector are:
The action procedure that gets called for each icon type selected for the family is a Pascal type function with the following interface:
FUNCTION IconAction(theType: ResType;
VAR theIcon: Handle;
yourDataPtr: Ptr): OSErr;
The parameter theIcon is passed by reference here so that your routine can modify the contents of the suite directly. The yourDataPtr parameter is the value passed when you called ForEachIconDo. It allows you to easily communicate with your application. The action procedure returns an OSErr. If any value other than noErr is returned, ForEachIconDo will stop processing immediately and return the error passed. (Note: This implies that the icons selected may only be partially operated on. There is no guaranteed order in which the icons get operated on.)
FUNCTION GetIconSuite(VAR theIconSuite: Handle;
theResID: INTEGER;
selector: IconSelectorValue): OSErr;
GetIconSuite will create a new icon family and fill it from the current resource chain with the icons of resource ID theResID and types indicated by selector. This is the call you will probably use most often to create an icon family. Note that if you SetResLoad(False) before making this call, the suite will be filled with unloaded resource handles.
FUNCTION PlotIconSuite(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theIconSuite: Handle): OSErr;
This call renders the proper icon image from the passed icon family based on the bit depth of
the display you are using and the rectangle that you have passed. The parameters align and transform are applied to the icon selected for drawing and then the icon is plotted into the current grafPort. PlotIconSuite chooses the appropriate icon based primarily on size. Once the proper icon size is determined (based on the destination rectangle), the present member of that size with the deepest bit depth that the current device can use is selected. A size category is considered present if the black-and-white member (with mask), 'ICN#', 'ics#', or 'icm#', is present. PlotIconSuite can be used for both picture accumulation and printing.
FUNCTION DisposeIconSuite(theIconSuite: Handle;
disposeData: BOOLEAN): OSErr;
This call disposes the icon family handle itself. In addition, if disposeData is true, any of the icon data handles that do not belong to a resource fork will also be disposed.
FUNCTION SetSuiteLabel(theSuite: Handle; theLabel: INTEGER): OSErr;
This call allows you to specify a label to draw an icon of this suite when no label is specified in PlotIconSuite. This is used primarily to ensure that a family passed to a system routine gets drawn with the proper label. The default label can be overridden by specifying a label in PlotIconSuite.
FUNCTION GetSuiteLabel(theSuite: Handle): INTEGER;
GetSuiteLabel returns the label previously set with SetSuiteLabel.
Icon Cache Calls
In addition to the icon family calls, icon caches have these additional calls:
FUNCTION MakeIconCache(VAR theHandle: Handle;
makeIcon: IconGetter;
yourDataPtr: UNIV Ptr): OSErr;
This call creates an empty icon cache similar to NewIconSuite, and associates the additional icon loading procedure and data value with the family.
FUNCTION LoadIconCache(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theIconCache: Handle): OSErr;
This call allows preflight loading of certain elements of your icon cache. This is handy if you suspect that certain drawing operations may occur at a time not convenient for loading your icon data (e.g., when your resource fork might not be in open chain). LoadIconCache takes the same parameters as PlotIconSuite and uses the same criteria to select the icon to load. The grafPort must be set properly before making this call since it is one of the criteria for determining the icon to load.
The following four calls are provided to change theData or theProc associated with an icon cache:
FUNCTION GetIconCacheData(theCache: Handle;
VAR theData: Ptr): OSErr;
FUNCTION SetIconCacheData(theCache: Handle;
theData: Ptr): OSErr;
FUNCTION GetIconCacheProc(theCache: Handle;
VAR theProc: IconGetter): OSErr;
FUNCTION SetIconCacheProc(theCache: Handle;
theProc: IconGetter): OSErr;
Plotting Icons Not Part of a Suite
The next calls are grouped because they are similar. They let you plot an icon to the screen without your creating an icon suite. They are also good if you have a 'cicn' instead of an icon family.
FUNCTION PlotIconID(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theResID: INTEGER): OSErr;
FUNCTION PlotCIconHandle(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theCIcon: CIconHandle): OSErr;
FUNCTION PlotIconMethod(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theMethod: IconGetter;
yourDataPtr: UNIV Ptr): OSErr;
FUNCTION PlotIconHandle(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theIcon: Handle): OSErr;
FUNCTION PlotSICNHandle(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theSICN: Handle): OSErr;
All these routines share the following parameters: theRect is the destination rectangle to draw the indicated icon into; align is the alignment method to use if the icon does not fit the rectangle given; transform indicates the desired appearance of the icon on the screen.
In PlotIconID, the parameter theResID is the resource ID of the family of 'ic' type resources to use. If the correct bit depth or the size required is not defined, the closest-fitting one will be used.
The PlotCIconHandle parameter theCIcon is a handle that you get to a standard QuickDraw color icon. Unlike PlotCIcon, PlotCIconHandle does not honor the current foreground and background colors. Call GetCIcon to load the icon. Dispose of it when you are done, since they can take up quite a bit of memory.
PlotIconMethod calls your IconGetter procedure, discussed earlier, to check for the existence of icon data.
PlotIconHandle will plot the data from an 'ICN#' or 'ICON' resource from its handle. It is a new version of PlotIcon.
PlotSICNHandle plots the data of a 'SICN' resource from its handle. Only 'SICN' resources with a single member, or one in which the second member is a mask for the first, will plot correctly.
All the functions return an error code if things did not go well with the drawing or, in the case of the PlotIconID call, if the indicated icon family could not be used.
Miscellaneous Calls
FUNCTION GetLabel(labelNumber: INTEGER;
VAR labelColor: RGBColor;
VAR labelString: Str255): OSErr;
This call returns the actual color and string used in the label menu of the Finder and the label’s Control Panel. This information is provided in case you wish to include the label text or color when displaying a file’s icon in your application.
FUNCTION IconSuiteToRgn(theRgn: RgnHandle;
iconRect: Rect;
align: IconAlignmentType;
theIconSuite: Handle): OSErr;
FUNCTION IconIDToRgn(theRgn: RgnHandle;
iconRect: Rect;
align: IconAlignmentType;
iconID: INTEGER): OSErr;
FUNCTION IconMethodToRgn(theRgn: RgnHandle;
iconRect: Rect;
align: IconAlignmentType;
theMethod: IconGetter;
yourDataPtr: Ptr): OSErr;
These routines will create a region from the mask of the icon selected by the iconRect and align values passed. They will allow you to do accurate hit testing and outline dragging of an icon in your application. The RgnHandle must have been previously allocated before you make this call.
FUNCTION RectInIconSuite(testRect: Rect;
iconRect: Rect;
align: IconAlignmentType;
theIconSuite: Handle): BOOLEAN;
FUNCTION RectInIconID(testRect: Rect;
iconRect: Rect;
align: IconAlignmentType;
iconID: INTEGER): BOOLEAN;
FUNCTION RectInIconMethod(testRect: Rect;
iconRect: Rect;
align: IconAlignmentType;
theMethod: IconGetter;
yourDataPtr: Ptr): BOOLEAN;
FUNCTION PtInIconSuite(testPt: Point;
iconRect: Rect;
align: IconAlignmentType;
theIconSuite: Handle): BOOLEAN;
FUNCTION PtInIconID(testPt: Point;
iconRect: Rect;
align: IconAlignmentType;
iconID: INTEGER): BOOLEAN;
FUNCTION PtInIconMethod(testPt: Point;
iconRect: Rect;
align: IconAlignmentType;
theMethod: IconGetter;
yourDataPtr: Ptr): BOOLEAN;
These calls hit test the passed Point or Rect against the icon indicated. The parameters iconRect and align, and the grafPort should be the same as when the icon was last drawn. The functions return true if the point is in the icon mask or if the rectangle intersects the icon mask.
Error Codes
The Icon Utilities will pass back any errors encountered during execution, so you can expect to see Memory Manager, Resource Manager, and other normal errors.
There is one error code defined specifically for the Icon Utilities routines that may be returned by the Icon plotting routines.
{ Pascal }
CONST
noMaskFound = -1000;
END;
/* C */
#define noMaskFound -1000
This error will be returned if the Icon Utilities package could not find or create a mask for the icon family. The Icon Utilities will use the correct mask for each icon size, if one is available. If no mask for a specific size is available, a mask will be created from any mask in the family, but if there are no 1 bit images and no mask in the family, plotting calls will fail with this error.
Type(def)s and Glue for Pascal and C
The Pascal and C interfaces are provided here to copy and paste since the current MPW standard interface files do not contain the glue for these calls. Electronic versions of this note are on AppleLink (Developer Support: Developer Services: Technical Documentation: Macintosh Technical Notes: Imaging: Graphics: Icon Drawing in 7.sit (Stuffit)) and the Developer CD (Technical Documentation: Macintosh Technical Notes: Imaging: Graphics: Icon Drawing in 7).
MPW C, Pascal, and Assembler files also have been submitted to AppleLink and the Developer CD, but their paths were not known when this note was written.
• Inside Macintosh, Volume VI, Finder Interface chapter
QD 19 - Fixed CLUT Devices and the Single Techno Nerd
QuickDraw
Written by: Guillermo A. Ortiz December 1992
Applications that need a given set of colors to look good or make use of color table animation can obtain undesired results in PowerBook 160, PowerBook 180, and PowerBook Duo Macintosh models. The reason for this is that these models sport Fixed Color Devices associated with the flat screen display. This Tech Note describes what a Fixed CLUT device is and presents some solutions to the challenges presented by this display type.
Topics
• Fixed CLUT video devices
• Color table animation and Fixed CLUT devices
• Different GDevice types and their implications
Introduction
Since the introduction of the Macintosh II, Inside Macintosh Volume V defined three types of graphics devices:
Indexed CLUT devices ( gdType = 0 )
Fixed CLUT devices ( gdType = 1 )
Direct RGB devices ( gdType = 2 )
In the case of indexed devices, values that range from 0 to 2n – 1 (where n is the depth of the device under consideration) point to entries in a table of RGB triplets, thus determining the color associated with a given pixel value. In the case of direct RGB devices, the pixel value is in itself an RGB triplet, therefore defining the color associated with the pixel.
Up to recently, the only type of indexed CLUT devices known to humanity has been gdType = 0 or Indexed CLUT devices; these are the devices that drive most display boards when set to depths between 1 and 8 (2 colors to 256 colors). As far as color is concerned, the main feature of indexed devices is that the color table for a given device can be changed either directly by using SetEntries or indirectly when the Palette Manager establishes the color environment in response to a palette associated with the frontmost window (if it has one.)
Fixed CLUT devices enter with the introduction of the PowerBook Duo, PowerBook 160, and PowerBook 180 portables. All these machines support 16-color gray displays (depth = 4); the trick is that although the video does have a color table, it can not be changed at all. What this means is that no color table animation is possible and that the palette manager can not give you the colors you want or affect palette animation.
Checking for the type of device is really simple. Once you have the device handle all you have to write is something like:
DisplayInfo.gdType = (*currDev) -> gdType;
Naturally, once the application knows it has to deal with a Fixed CLUT device, it may want to do something based on this information.
So What!
At this point the smart reader is probably starting to wonder what kind of help this Tech Note is going to provide as far as not having to stay alone at home this Friday evening: Sadly enough the answer is none. Nevertheless it can help avoid support calls from PowerBook users when their favorite application starts acting weird.
Now, the first thing to emphasize is that most developers don’t have to worry about this—it is not as if your word processing application is going to start crashing. However, applications that by their nature have to modify the color environment to run properly have to take some precautions.
We will discuss some scenarios and the implications for each one. Other possibilities may exist, but these will help you understand the issues.
• Non-Color-Intensive Applications Need Not to Worry
Applications that deal with text and black-and-white stuff should not be concerned. Even applications that provide limited color capabilities will have no problem.
• Color-Enhanced Applications
Certain applications such as games and presentation packages require a given set of colors to look “cool.” Probably the Palette Manager is used in order to assure that the minimal set of colors is present. Applications like these need to make sure there is a fallback similar to the one used when the application is running in a black-and-white environment. Note that prompting the user to change the depth won’t do much good.
• Color-Intensive Applications
Applications that require heavy manipulation of the color environment to do their stuff need to be ready to take the path taken when the machine the user is on has no color or can not be set to the optimum depth. Applications that call the video driver directly such as those that animate colors by calling the _Control routine especially need to make sure the device in question is capable of color table changing; the control call returns an error -17 (controlErr - Driver can not respond to Control call) if SetEntries or DirectSetEntries is tried.
Note 1: The PowerBook Duo can be docked to a number of different docking stations, the currently available docking stations are:
a. Duo Dock. In this case the flat display is not used at all and the main device becomes an Indexed CLUT device with depths depending on the monitor being used.
b. Mini Dock. The main display is still in use and the monitor configuration for the machine becomes a two-display system with one Indexed CLUT device (external display) and a Fixed CLUT device (flat display).
Note 2: PowerBook Duo, PowerBook 160, and PowerBook 180 Macintosh computers can be configured in a display mode called Mirroring using the PowerBook Display control panel. In this configuration the system sees two devices that share the same bounds. The result is that drawing to the main device results in drawing into both screens with QuickDraw taking care of the details such as different depths and color/black-and-white settings.
In Conclusion
Fixed CLUT devices add a little twist to the things that an application developer has to be aware of. With the popularity of the PowerBook line, it becomes really important that applications know how to configure in this case in order to continue providing smooth performance under the varied conditions now existent in the Macintosh family of computers.
Further Reference:
• Inside Macintosh, Volume VI, The Graphics Devices Manager
• Macintosh Duo System Developer Note (Available on the Developer CD)
• Macintosh PowerBook 160 and Macintosh PowerBook 180 Developer Note (Available on the Developer CD)
QD 20 - _PackBits : Things You Wanted to Know About* *But Were Afraid to Ask
QuickDraw
Revised by: Guillermo Ortiz, Jon Zap, and Forrest Tanaka January 1992
Written by: Cameron Birse November 1987
This Technical Note describes the format of data packed by the Toolbox utility _PackBits and documents a change to the srcBytes limit and possible worst case. Although you can simply unpack this data using _UnPackBits, Apple provides this information for the terminally curious and for those manipulating MacPaint® documents or PICT files by hand.
Warning: This format information is subject to change.
Changes since November 1990: A warning has been added about the handling of a flag-counter byte value of -128.
Length Doesn’t Matter
Inside Macintosh, Volume I-470, describes the Pascal interface to the _PackBits trap as follows:
The accompanying text states that srcBytes, the length of your uncompressed data, should not be greater than 127, and that in the worst case, the compressed data can be srcBytes + 1. To pack more than 127 bytes, you had to break the data up into 127-byte groups and call _PackBits on each group. Beginning with system software version 6.0.2, this limit of 127 bytes is no longer valid. The new limit is 32,767 bytes, which is the maximum positive number that srcBytes can hold. The worst case can be determined according to the following formula:
(srcBytes + (srcBytes+126) DIV 127)
which is comparable to what you would get if you broke up the data into 127-byte groups and picked up an additional byte for each group.
Mommy, How Do They Make Packed Bits?
The first byte is a flag-counter byte that specifies whether or not the the following data is packed, and the number of bytes involved. If this first byte is a negative number, then the following data is packed. In this case, the number is the two’s complement of a zero-based count of the number of times the data byte repeats when expanded. There is one data byte following this first byte in packed data. The byte after the data byte is the next flag-counter byte.
If the flag-counter byte is a positive number, then the following data is unpacked. In this case, the number is a zero-based count of the number of incompressible data bytes that follow. There are (flag-counter+1) data bytes following the flag-counter byte. The byte after the last data byte is the next flag-counter byte.
Note that there is no way to know, given a pointer to the start of packed data, when you have reached the end of the packed data. This is why you need to know either the length of the packed or unpacked data before you start unpacking. _UnPackBits requires the length of the unpacked data.
Warning: _PackBits never generates the value -128 ($80) as a flag-counter byte, but a few PackBits-like routines that are built into some applications do. _UnpackBits handles this situation by skipping any flag-counter byte with this value and interpreting the next byte as the next flag-counter byte. If you’re writing your own UnpackBits-like routine, make sure it handles this situation in the same way.
Consider the following example:
Unpacked data:
AA AA AA 80 00 2A AA AA AA AA 80 00 2A 22 AA AA AA AA AA AA AA AA AA AA
After being packed by _PackBits:
FE AA ; (-(-2)+1) = 3 bytes of the pattern $AA
02 80 00 2A ; (2)+1 = 3 bytes of discrete data
FD AA ; (-(-3)+1) = 4 bytes of the pattern $AA
03 80 00 2A 22 ; (3)+1 = 4 bytes of discrete data
F7 AA ; (-(-9)+1) = 10 bytes of the pattern $AA
or
FE AA 02 80 00 2A FD AA 03 80 00 2A 22 F7 AA
* * * * *
The bytes with the asterisk (*) under them are the flag-counter bytes. _PackBits packs the data only when there are three or more consecutive bytes with the same data; otherwise it just copies the data byte for byte (and adds the count byte).
Note: The data associated with some PICT opcodes, $0098 (PackBitsRect) and $0099 (PackBitsRgn), contain PixData which is basically made of _PackBits data. It should be noted, though, that the format for PixData includes a byteCount or length in addition to the data described in this Note.
For example, the following is the result of decoding a sample PICT2:
/* Now we have the scan line data packed as follows:
[bytecount for current scan line] [data as defined above]
If rowBytes is > 250 then byteCount is a word else is a byte
(in this case, byteCount is a byte)
note that each unpacked row adds to 30 rowBytes
*/
/* line 1, byte count is 2 (best case for a row) */
02
E3 FF /* -(-29) + 1 = 30 FF's */
/* line 2, byte count is 19 (0x13) */
13
01 FF 23 /* 1+1 data bytes */
FE 00 /* -(-2)+1 0's */
FC 23 /* -(-4)+1 0x23's */
FE 00 /* 3 0's */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
00 FF /* 1 data byte */
/* line 3, byte count is 28 */
1C
02 FF 00 23 /* 3 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
04 00 23 00 00 FF /* 5 data bytes */
/* line 4, byte count is 31 (worst case for a row) */
1F
03 FF 00 00 23 /* 4 data bytes */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
02 23 00 FF /* 3 data bytes */
/* line 5, byte count is 28 */
1C
01 FF 00 /* 2 data bytes */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
00 FF /* 1 data byte */
/* line 6, byte count is 18 */
12
00 FF /* 1 data byte */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
FD 23 /* 4 0x23's */
00 FF /* 1 data byte */
/* line 7, byte count is 2 (best case for a row) */
02
E3 FF /* 30 0xFF's */
00 /* pad so next command starts at word boundary */
00FF /*end of pic */
};
Further Reference:
• Inside Macintosh, Volume I-465, The Toolbox Utilities
• Inside Macintosh, Volume V-39, Color QuickDraw
• Technical Note M.PT.MacPaintDoc —
MacPaint Document Format
MacPaint is a registered trademark of Claris Corporation.
QD 21 - Of Time and Space and _CopyBits
QuickDraw
Written by: Forrest Tanaka June 1990
This Technical Note describes the various factors that can influence the speed of _CopyBits so that developers can set up conditions to achieve the best performance for the particular situation.
Can You Influence the Speed of _CopyBits?
_CopyBits has never been an “easy” QuickDraw routine, like _LineTo or even _OpenPort. Most programmers who are just beginning to adjust themselves to the Macintosh usually have to give _CopyBits a few tries before the right bits copy to the right places. Even many who feel that they have become Macintosh programmers still see reflections in their monitors of furrows between their eyebrows as they begin to press the key labelled “C.”
_CopyBits is one of those routines that is so full of subtlety, it has the beginnings of something that could be considered to be personality. One subtlety involves the second most important thought that’s on the minds of any computer programmer: execution speed. Why is _CopyBits fast? Why is it slow? Can I influence its speed? Is there really a clandestine state of reason? Is there a price to speed?
Influences on the Speed of _CopyBits
Yes, you can influence the speed of _CopyBits. Yes, it’s even predictable. And yes, it’s possible that you have to compromise to get the maximum speed. This Note is intended to give you a deeper understanding of the ways that the speed of _CopyBits can be affected; and hopefully you can then set up conditions for a _CopyBits call without the disturbing notion that someone else might be doing the same thing just a little bit better than you.
This Note talks about every factor that affects the speed of _CopyBits that I can think of and that can be reasonably controlled by a programmer or the person using an application. There are other factors not mentioned in this Note because I felt that they were just too esoteric to describe with any meaning.
In each case, this Note tries to give real-life examples showing the effect of each factor. These examples are just to give you a relative idea of the importance of each effect. In real life, the effects of the different factors give results that could be a lot different from the results presented in this Note. Each example is based on 100 _CopyBits calls from an off-screen pixel map to the screen on a Macintosh IIcx with an Apple Extended Video Card which is running System Software 6.0.5 and 32-Bit QuickDraw 1.2. The off-screen pixel map is eight bits deep with the standard eight-bit color table and 256 pixels high by 256 pixels wide. The screen is also in eight-bit color mode. Calling _CopyBits to copy the entire off-screen pixel map to the screen 100 times takes 204 ticks, and this Note refers to this figure as the “standard test.” Since a tick on a Macintosh is approximately 1/60 of a second, the standard test runs at slightly less than 30 frames per second. As this Note discusses each factor, it presents an example with that factor changing and all other factors remaining the same as the standard test, which allows you to compare performance of the changed factor to that of the standard test of 204 ticks.
What follows is a discussion of each factor that can influence the speed of _CopyBits, in no particular order.
Dimensions of the Copied Area
One of the most obvious factors has to do with the dimensions of the copied area. _CopyBits takes as parameters two rectangles which specify the portion of the source pixel map from which you want to copy and the portion of the destination pixel map to which you want to copy it. All other factors being equal, the larger the rectangles, the more pixels _CopyBits has to copy and the longer it takes to do the job. To keep _CopyBits as fast as possible, copy the smallest rectangle possible.
Modifying the standard test so that _CopyBits only copies a 128-pixel wide by 128-pixel tall area produces a result of 109 ticks, which compares to the 204 tick performance for a 256-pixel wide by 256-pixel tall area.
QuickDraw is usually faster drawing wide things than it is drawing tall things, because consecutive pixels in memory are displayed horizontally. Drawing a series of pixels that are next to each other horizontally is easy because QuickDraw simply has to set consecutive memory locations, while drawing a series of pixels that are next to each other vertically is just a little bit harder because the address of each pixel must be calculated. _CopyBits is no exception to this general rule; it copies a row of pixels, goes to the next row, copies that row, goes to the next row, and so on. The time spent going between rows is a lot more than the time going between pixels on one row, so the effect is that _CopyBits is faster copying a short and wide section of a pixel map than it is copying a tall and narrow one. To keep _CopyBits as fast as possible, copy the shortest rectangle possible.
Modifying the standard test again so that the source and destination rectangles are 256 pixels wide by 50 pixels tall produces a result of 110 ticks, while modifying it so that the source and destination rectangles are 50 pixels wide by 256 pixels tall results in a time of 123 ticks. These 13 ticks may not seem like a big deal, but combined with other factors, there may be a case where they make a big difference.
Shape and Size of the Clip, Visible, and Mask Regions
_CopyBits always makes sure that it stays within the lines, so to speak. _CopyBits copies pixels clipped to the maskRgn that you pass as the last parameter to the call. If the destination is the current GrafPort, _CopyBits additionally clips to a region that’s the intersection of the clipRgn and visRgn of the port. If the intersection of these three regions is not rectangular, then _CopyBits has to check each pixel to make sure it falls within the intersection, and this check slows _CopyBits down. If the intersection of these three regions is rectangular, then _CopyBits takes the fast case of copying constant-sized rows. To keep _CopyBits as fast as possible, make sure the intersection of the clipRgn and visRgn of the destination GrafPort and the maskRgn is rectangular. Of course, if the destination GrafPort is a window, then the visRgn is under the user’s control.
In general, if the region that you are copying into has straight vertical edges for the most part, the time penalty of using a non-rectangular region is not that bad. Regions that only have small portions that are straight and vertical are the ones that slow _CopyBits down in a big way. Regions that are twisted or that have holes or islands can also have a big effect upon the speed, depending upon how complicated they are. As a rule of thumb, if a region looks like it slows _CopyBits, it probably does.
Modifying the standard test so the maskRgn is set to a circle that inscribes the example pixel map results in a time of 303 ticks, which is considerably longer than the standard test result of 204 ticks that involved copying a much larger area. Modifying the maskRgn to a square with 226 pixels per side, which has about the same total area of the circle just used, results in a time of 176 ticks.
Transfer Modes
Macintoshes without Color QuickDraw have eight transfer modes that work with _CopyBits, while those Macintoshes with Color QuickDraw get an additional nine modes. Because the algorithms for each of these modes can be pretty different from the others, the time it takes _CopyBits to work with each of these modes can vary radically. For several of these modes, the speed of _CopyBits can vary a lot depending upon the particular image being copied and the image over which this image is copied. It can also vary non-linearly depending upon the depth of the pixel maps. The arithmetic modes in particular are highly optimized for 32-bit deep pixel maps.
The standard test copies a fairly average-looking ray-traced image to a white background. Modifying the standard test to erase the background between each of the 100 calls to _CopyBits produced the following results for the modes listed (the tests were obviously also changed to reflect the proper mode. In addition, to make the results a little more meaningful, the time it took to erase the background has been subtracted from each result.
Of course, the amount of time taken by some of these modes can be changed by changing the image to copy and the image over which it is copied. These figures are just to give an idea of how fast or slow some of these modes are in this particular situation.
There is actually one more mode which is not mentioned: ditherCopy. Apple introduced this mode with 32-Bit QuickDraw, and it makes _CopyBits do error-diffusion dithering when copying a pixel map from one depth to a pixel map of a lesser depth or to a pixel map of the same depth with a different color table. The speed of this transfer mode can be very fast or very slow, depending upon what pixel depths and colors are used and the particular image being copied. The ditherCopy mode is not included in the table since the range of figures is potentially very large; play with it and see for yourself. For more information about this mode, refer to the Color QuickDraw chapter in Inside Macintosh, Volume VI and the 32-Bit QuickDraw Developers’ Notes from APDA.
Colorization
There is a variation of _CopyBits if the destination pixel map is the current port and the foreground color is not black or the background color is not white. If this is the case, then the source image is colorized when it’s copied. For details, see Technical Note #163, Adding Color with _CopyBits. Because this colorization requires extra processing, _CopyBits slows down. To keep _CopyBits as fast as possible, make sure the foreground color is black, the background color is white, and that the current GDevice pixel map’s color table has white in the first position and black in the last position.
Modifying the standard test so that the foreground color is pure red and the background color pure blue produces a result of 579 ticks.
Pixel Alignment
The alignment of pixels in the source pixel map relative to their alignment the destination pixel map can be surprisingly important to the speed of _CopyBits, but what is pixel alignment? Following is an example to demonstrate the concept of pixel alignment. Imagine you want to perform a _CopyBits on a one-bit-per-pixel off-screen pixel map into a window on a one-bit-per-pixel screen, and the window is three pixels from the left edge of the screen.
If you copy the entire off-screen pixel map to the left edge of the window, then _CopyBits must realign the pixels. Since the leftmost pixels of the off-screen pixel map are on a byte boundary, but the left edge of the window is three pixels away from a byte boundary, _CopyBits has to shift (or realign) each byte from the off-screen pixel map by three pixels before placing it on the screen. The process of aligning the pixels slows down _CopyBits.
Figure 1 shows an example of this realignment. An off-screen bit map specified by a pointer to a BitMap called offScreen is being copied to a window specified by a WindowPtr called window. window, which is 256 pixels wide and 256 pixels high, is positioned 50 pixels from the top of the screen and three pixels from the left edge of the screen. The screen has 512 pixels horizontally and 342 pixels vertically. The source rectangle that is passed to _CopyBits is sourceRect and the destination rectangle is destinationRect. Because offScreen is misaligned by three pixels, _CopyBits has to shift offScreen by three pixels before placing the image on the screen.
Figure 1–offscreen Needs Realignment
By adjusting the off-screen pixel map so that its leftmost pixels are also three pixels away from a byte boundary, _CopyBits can just copy the bytes without shifting, which is a lot faster. This example holds true on all Macintosh models, whether they have Color QuickDraw or not. To keep _CopyBits as fast as possible, make sure the pixels in memory are aligned with the pixels on the screen. Figure 2 shows the same situation as Figure 1, except that offScreen is now properly aligned to window.
Figure 2–offscreen Aligned
Many, if not most, Color QuickDraw Macintoshes have video cards that can display one pixel per byte, so one would think that pixel alignment does not apply in these cases, since all pixels are at byte boundaries. This statement is true enough, but there is still another kind of alignment that should be done on these machines. Macintoshes with Color QuickDraw generally have full 32-bit microprocessors, and these microprocessors are at their fastest when they can transfer long words aligned on long-word boundaries in memory.
Modifying the last example so that the off-screen pixel map and the screen are both eight-bits-per-pixel, the pixel at the extreme top left corner of the off-screen pixel map is located at a long-word boundary, because the Macintosh Memory Manager forces it to be located there; however, the pixel at the extreme top left corner of the window is located three bytes away from the previous long-word boundary. No bit shifting is needed, because each pixel takes up a whole byte, but _CopyBits does have to take the non-optimum case of copying long words on non-long-word boundaries. This case works fine, but it is not quite as fast as it could be. To keep _CopyBits as fast as possible, make sure pixels in the source and destination pixel maps are aligned on long-word boundaries.
Since 1984, Macintosh programmers have been told that rowBytes must be even. That is still true, but to allow _CopyBits to copy an entire pixel map on long-word boundaries, rowBytes must be a multiple of four so that every line in a pixel map begins on a long-word boundary. The following formula can be used to find the minimum rowBytes needed for a pixel map’s bounds rectangle with right and left coordinates of bounds.right and bounds.left, and a pixel depth of pixelDepth:
Off-screen GWorld support, which was introduced with 32-Bit QuickDraw, can automatically set up a pixel map so that it’s properly aligned to any part of the destination pixel map or bit map. You can specify that you want this by passing zero for the pixel depth and passing the rectangle of the destination area in global coordinates. See the 32-Bit QuickDraw Developers’ Notes and “Braving Offscreen Worlds” in d e v e l o p, January 1990 for details.
The way that _NewGWorld aligns a GWorld is to set up the off-screen pixel map so that its rowBytes is four bytes wider than one would normally calculate. Four bytes is the maximum amount that any pixel map would have to be realigned at any pixel depth. The bounds rectangle’s left coordinate is set to the negative of the left coordinate of the destination rectangle in global coordinates modulo (32 / pixel depth), because this is maximum amount that a pixel map must be shifted to achieve perfect alignment. To build on the earlier example, assume you have a 128-pixel wide, eight-bit deep, off-screen pixel map to copy to a window that is three pixels away from the left edge of an eight-bit color screen.
First, the rowBytes for the off-screen pixel map is set to 131 to allow room for realignment. To align the off-screen pixel map to the on-screen window, the left coordinate of the off-screen bit map’s bounds is set to -3 and the right coordinate is still at 128. Notice that the off-screen pixel map’s bounds is now 131 pixels wide. Now, the pixels in the off-screen pixel map with a horizontal coordinate of 0 are located three bytes away from the previous long-word boundary. The pixels on the left edge of the window are also located three bytes away from the previous long-word boundary, so _CopyBits can copy long words on long-word boundaries.
If a user moves the window so that it’s two pixels from the left edge of the screen, the off-screen pixel map must be realigned. _UpdateGWorld is used to do this. It changes the left coordinate of the off-screen pixel map’s bounds rectangle to -2 and then it shifts all the pixels in the off-screen pixel map one pixel to the left. The extra four bytes in each row provide the room for this shifting. (Gives you some new respect for the off-screen support, doesn’t it?)
This same discussion applies to any pixel depth, though shallower pixel depths require bit shifting rather than byte shifting. The same principles apply, though. Notice that in a 32-bit deep pixel map, all pixels are aligned on long-word boundaries, so no bit shifting or byte shifting ever needs to be done on one of those. _NewGWorld still adds four to rowBytes even in this case, however.
Modifying the standard test so that the source and destination pixel maps are four bits deep with perfect pixel alignment produces a result of 78 ticks; however, if the destination pixel map is one pixel left of perfect alignment, the result is 228 ticks.
Speed of the Hardware, Of Course
Obviously, the speed of the machine your application is running on affects the speed of _CopyBits. To make _CopyBits as fast as possible, spend a lot of money. However, there is more to the speed of _CopyBits than the speed of the Macintosh itself. When the Macintosh 128K was released, there was only one place for pixel images: main memory. Today, the situation is more complicated. If you have a modular Macintosh, the pixel image for the screen is in the memory of a NuBus™ video card. If you have a Macintosh IIci, you can optionally abandon the NuBus video card and use on-board video which takes up part of main memory. If you have an 8•24 GC card with enough memory, the pixel images can be cached in the card’s memory along with the screen’s pixel image.
All of these different locations have different access speeds, and that can affect the speed of _CopyBits. Additionally, different Macintoshes have different RAM access speeds. The Macintosh II, IIx, IIcx, and SE/30 have faster RAM than the Macintosh Plus or SE. The Macintosh IIci RAM access speed is faster still, and the Macintosh IIfx has faster RAM access than the IIci. Different video cards have different access speeds. The IIci has a cache card option which can vastly speed up on-board video RAM access speed. Third-party video cards that work in the Processor Direct Slot of the Macintosh SE and SE/30 have their own speed characteristics as well.
There can also be a speed cost for crossing the different areas. If _CopyBits copies between main memory and a NuBus video card, the image data has to be transferred across NuBus. NuBus is a speed bottleneck, so copying an image across NuBus is slower than copying the image from one part of the screen to another or copying from one part of main memory to another. Modifying the standard test to create two windows and two off-screen pixel maps—all eight bits deep with the standard color table then doing every combination of copying between off-screens, between windows, and between off-screens and windows produces the following results:
Off-screen to off-screen: 147
Screen to screen: 188
Off-screen to screen: 204
Screen to off-screen: 201
Performing the standard test on a Macintosh IIfx running System Software 6.0.5 with an Apple Extended Video Card yields a result of 153 ticks, which is not too shabby considering that the transfer is still going through NuBus.
Depth of Pixel Maps
This factor is pretty obvious and is sort of similar to the effect of the dimensions of the copied area: the more bits per pixel there are in the pixel map to copy, the more memory that _CopyBits has to move and the longer it takes to get the job done, assuming that the source and destination pixel maps have the same depth. To make _CopyBits as fast as possible, make sure the pixel maps are as shallow as possible.
If _CopyBits has to copy to a pixel map that has a different depth from the source pixel map, the relationship between speed and depth becomes more complicated. There is a tradeoff between the time taken to change the depth of an image and the absolute amount of data that has to be processed. Copying from a 1-bit deep pixel map to a 32-bit deep pixel map is not that slow because the amount of image data in the 1-bit deep pixel map is so small.
Modifying the standard test to transfer a four-bit deep pixel map to another four-bit deep pixel map produces a result of 78 ticks.
Color Mapping
Color QuickDraw expects a color table attached to every indexed pixel map. Color tables specify what color each pixel value in the pixel map represents. When an application calls _CopyBits to copy a pixel map into another pixel map, _CopyBits reproduces the colors of the image in the source pixel map as closely as possible—even if the colors available in the destination pixel map are different than those available in the source pixel map. This reproduction is done through a process called “color mapping.”
When color mapping is done, the source pixel values are transformed into RGBColor records using the source pixel map’s color table. These RGBColor records are passed to _Color2Index which finds the pixel values of the closest available colors in the current GDevice pixel map’s color table. This same process is done when the source and destination pixel maps have differing depths. The color table attached to the destination pixel map is not used in color mapping. The colors available in the current GDevice pixel map’s color table are used instead. So, the destination pixel map must have the same colors for the same pixel values as the current GDevice. Otherwise, the resulting image in the destination pixel map gets the wrong colors. See Inside Macintosh, Volume V-141, The Color Manager, for a description of _Color2Index. It’s also helpful to read the “Inverse Tables” section in the same chapter on page V-137.
Now, if the source color table contains virtually the same colors for the same pixel values as the current GDevice pixel map’s color table, then any particular pixel value has the same color regardless of whether it is in the source or destination pixel map. In this case, color mapping is a waste of time, because the pixels can be copied directly from the source pixel map to the destination pixel map without a loss of color fidelity. _CopyBits takes advantage of this special case to yield some big speed improvements. How is this special case detected? Before this question is answered, it’s useful to understand how Color QuickDraw uses color tables.
The ctSeed Field
The first field in a color table is the ctSeed field. This LongInt can be thought of as the color table’s version of the scrapCount field of the desk scrap. Whenever an application calls _ZeroScrap, the desk scrap’s scrapCount is changed. An application can tell that the desk scrap has changed by checking to see if the scrapCount has changed. Similarly, whenever the contents of a color table are changed in any way, the ctSeed field should be changed to indicate to anyone using that color table that it has been modified.
Additionally, Color QuickDraw often uses the ctSeed as a fast check for color table equality. If two color tables have the same ctSeed, then Color QuickDraw often assumes that their contents are equivalent.
After creating a new color table, an application has to get a valid value for the ctSeed field, and it can do so with the _GetCTSeed routine. This routine generates a valid ctSeed value suitable for a new color table. See Inside Macintosh, Volume V-143, The Color Manager, for a description of _GetCTSeed.
System Software 7.0 and 32-Bit QuickDraw each offer a routine called _CTabChanged which should be called after a color table is modified. It takes a handle to the changed color table as a parameter. If the _CTabChanged routine is not available, then the application should instead change ctSeed to a different valid value by calling _GetCTSeed and assigning the result to ctSeed, just like it’s done when the application creates a new color table. You must use either one of these methods to tell Color QuickDraw that the color table has changed, or else the modified color table could be confused with the old color table, or with some other color table—this is especially critical if an 8•24 GC card is being used. See the 32-Bit QuickDraw Developers’ Notes for details about the _CTabChanged routine.
The ctFlags Field
The ctFlags field is used as a set of flags that indicate some characteristics of the color table. Currently, only the top two bits of ctFlags are of any interest to developers. The most significant bit of ctFlags (bit 15) indicates whether the color table is a sequential color table or an indexed color table. Bit 14 indicates that the color table is a special kind of sequential table if it is set. In these kinds of color tables, the value fields indicate a palette entry in the destination window’s palette. See the Palette Manager section of the 32-Bit QuickDraw Developers’ Notes for a discussion about this capability.
Sequential Color Tables
If bit 15 of ctFlags is set, the color table is a sequential color table. Sequential color tables are usually found attached to GDevice pixel maps and to GWorld pixel maps.
In sequential color tables, the position of each color in the color table indicates the pixel value to which it corresponds. For example, the fifth entry in a sequential color table always has a pixel value of four (pixel values start at zero). The value field of each ColorSpec is not defined in sequential color tables, though they are used in color tables for screen GDevice records to indicate that a particular color is reserved, protected, or both.
Indexed Color Tables
If bit 15 and 14 of ctFlags are clear, the color table is an indexed color table. In indexed color tables, the value field of each ColorSpec indicates the pixel value of the RGB in that ColorSpec. For example, if the fifth ColorSpec in the color table has a value field containing 10, then that color has a pixel value of 10, not 4, as it would have been if this were a sequential color table.
Color Mapping or Non-Color Mapping
As noted before, _CopyBits can detect whether it has to do color mapping or not, so that it can take advantage of the speed benefits of no color mapping if possible. How is this done? First, _CopyBits checks to see if the ctSeed field of the source and destination color tables are the same and if the source and destination pixel maps have the same depths. If both of these conditions are true, then _CopyBits assumes that the two color tables are identical and it just copies the pixels directly without color mapping. If the ctSeed fields are different, _CopyBits checks manually through all of the colors in the source pixel map’s color table map to see if they map to the same pixel values in the current GDevice pixel map’s color table as they do in their own color table. If they do, then _CopyBits again takes the fast case.
So to keep _CopyBits as fast as possible, make sure that the source and destination color tables have virtually the same colors for the same pixel values. This applies even if one color table is an indexed color table and the other is a sequential color table, or if the source and destination color tables are both indexed but the order of the ColorSpec records differ.
Modifying the standard test so that the source pixel map has a color table that is the reverse of the standard eight-bit system color table (the grays have low pixel values and the light pinks and yellows have high pixel values) and the destination pixel map has the standard eight-bit system color table produces a result of 470 ticks.
By the way, color tables do not make any sense for direct pixel maps, so this discussion does not apply to them. Direct pixel maps do have a color table attached to them, but they’re just there so that an application that assumes that a color table is attached does not bomb.
Scaling
If the source and destination rectangles are the same size, _CopyBits has the fairly easy task of just transferring the pixels from the source pixel map to the destination pixel map; however, if the source and destination rectangles are different sizes, _CopyBits has to scale the copied image, which slows it down a lot. To keep _CopyBits as fast as possible, make sure the source and destination rectangles have the exact same dimensions.
Modifying the standard test to copy a 128 by 128 pixel portion of the source pixel map to the whole 256 by 256 pixel window produces a result of 1,159 ticks.
Of Time and Space
Hopefully, this Note makes it a lot clearer to you how to set up a situation in which your _CopyBits calls are as fast as your situation allows. It’s important to realize that this Note does not cover every single factor that has an influence on the speed of _CopyBits. There are many more factors which are just too unpredictable. For example, _CopyBits is highly optimized for many special cases, and those optimizations can have a big effect on the speed of the copy. Also, the speed of _CopyBits can be affected by interrupt-level tasks. It’s up to you to fine tune your programs to your particular situations.
Further Reference:
• Inside Macintosh, Volume I, QuickDraw
• Inside Macintosh, Volume V, The Color Manager
• Inside Macintosh, Volume VI, Color QuickDraw
• Technical Note M.IM.ColorCopyBits, Adding Color With _CopyBits
• d e v e l o p, January 1990, “Realistic Color for Real-World Applications”
• d e v e l o p, January 1990, “Braving Offscreen GWorlds”
• 32-Bit QuickDraw Developers’ Notes (APDA)
NuBus is a trademark of Texas Instruments
QD 505 - Basic QuickDraw Q&As
QuickDraw
Revised by: Developer Support Center September 1993
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As for this month:
Determining whether CopyBits to a PICT was successful
Random function requires prior InitGraf call
GetIconCacheData & SetIconCacheData bug and workaround
DrawText and DrawString patched to be script aware
Determining whether CopyBits to a PICT was successful
Date Written: 1/7/93
Last reviewed: 3/1/93
If I’m recording a PICT and doing a CopyBits of a really big image into the PICT, how can I determine whether I’m out of memory?
___
The only reliable way to see whether a CopyBits to a PICT succeeded is after the fact. You need to test the PICT’s picFrame rect (Inside Macintosh Volume V, page V-87) to see whether it’s empty after the CopyBits. The test would look like:
If (EmptyRect(&(**myPicture).picFrame))
/* CopyBits failed */
Random function requires prior InitGraf call
Date Written: 12/16/92
Last reviewed: 3/1/93
The Random function call listed in QuickDraw.h can’t be called from MPW tools without crashing my system. It appears to work when the function is called from applications or cdevs. What could be causing this problem?
___
Use SANE’s RandomX function instead of QuickDraw’s Random function if possible because it gives you better randomness. If you do use QuickDraw’s Random function, be sure to call InitGraf before calling Random from any application or tool. InitGraf initializes a set of QuickDraw global variables for use with the QuickDraw tools; these globals must be initialized because the Random function uses one of them as a seed to generate the random number.
Normally, it’s not good practice to call initialization routines from within an MPW tool, but calling InitGraf is OK. For more information on which initialization routines are OK to call and which ones aren’t, see page 7 in the MPW Tools chapter of Building and Managing Programs in MPW.
Sometimes it isn’t obvious when you need to call InitGraf before using the Random function. For example, if you’re using the Macintosh serial tool in a faceless background application, you’ll need to initialize QuickDraw because the tool calls Random.
GetIconCacheData & SetIconCacheData bug and workaround
Date Written: 12/8/92
Last reviewed: 3/1/93
The Icon Utilities routine GetIconCacheData leaves two bytes of garbage on the stack. This surfaced as a problem for me because it prevented a saved register from getting restored properly. SetIconCacheData probably has the same problem, since it calls the same trap internally. I solved the problem by encapsulating GetIconCacheData within my own static function, like so:
I then call GetIconCacheData normally. The #define redirects my call to my static wrapper function. The extra two bytes on the stack are recovered when the wrapper function UNLKs and returns. This method has the advantage that the calling code will still work even after the trap is fixed. Am I correct?
___
You’re quite correct; this is a bug in GetIconCacheData and SetIconCacheData. Here’s the offending code from the source:
EXIT MOVEA.L (SP)+, A0 ; Pop return address into A0
ADDQ.L #6, SP ; Point stack at return value
MOVE.W D0, (SP) ; Put return value on the stack
JMP (A0) ; Return
As you can see, the exit routine is adding 6 to the stack to clear up the input parameters instead of 8 (handle and handle), so an extra word of garbage is being left on the stack. Thanks for letting us know about the problem.
DrawText and DrawString patched to be script aware
Date Written: 11/16/92
Last reviewed: 6/14/93
While localizing our software, we were told not to assume that a character is only one byte, and thus not to use DrawChar. Does this mean that we can’t use DrawText or DrawString?
___
DrawChar takes a one-byte character as a parameter, so it isn’t suitable for drawing a character whose internal representation requires two bytes. However, DrawText and DrawString (both end up in the same bottleneck procedure StdText) are patched in script-aware systems, and do recognize whether a given byte in a given font-script still corresponds to a one-byte character, or is the first byte of a two-byte character. In the latter case, it transparently fetches the next byte, and looks up the right glyph encoded by a double byte, before actually drawing the glyph.
QuickDraw globals at INIT time
Date Written: 6/1/92
Last reviewed: 9/15/92
If I call InitGraf before I reference CurrentA5, will CurrentA5 be valid and can the QuickDraw globals be referenced off it? The screenBits bounds values seem screwy on some machines. Does the problem lie with CurrentA5? Should I be referencing A5?
___
Here’s the process used by ShowINIT, which is remarkably compatible with system software and other INITs (and it had better be, because it’s used by more than half the system extensions available):
1. It saves the value in the CurrentA5 global to restore it later.
2. It points the A5 register at 4 bytes of storage for use by the system.
3. It copies the value now in A5 into the CurrentA5 global.
4. It calls InitGraf, passing a pointer to the thePort field of a QuickDraw globals structure.
5. It opens a port and draws as necessary. [This is where all the functionality goes.]
6. After it’s done, it closes its port.
7. It copies the value saved in step (1) into the A5 register.
8. It copies the restored A5 value into the CurrentA5 global.
To summarize, ShowINIT saves the A5, creates and initializes its own A5 world, does its drawing, then restores the previous A5 world. For more information on this subject, see the Macintosh Technical Note “Stand-Alone Code.”
Macintosh QuickDraw LineTo bug and workaround
Date Written: 4/23/92
Last reviewed: 7/13/92
Our zooming function crashes into flames when we pass valid coordinate values to LineTo, as in the following example:
SetPort(myPort);
MoveTo(154,31619);
LineTo(74, -31742); (* You are dead! *)
What can we do to avoid LineTo crashes like this?
___
The QuickDraw Engineering group is aware of the problem you described. The bug probably is going to be fixed in the next release that includes bug fixes. Given that waiting for a system solution may demand more patience than is reasonable, you may want to consider including in your software some form of workaround that will prevent your users from crashing every time an operation takes the software to the limits of QuickDraw.
One way to approach this problem is to replace the lineProc bottleneck. All you need to do is to check the distance between the current pen position and the line’s end, and when the distance becomes too big (let’s say more than 32000) your procedure will call StdLine a couple of times, splitting the operation in two.
Replacing the bottlenecks is a very straightforward operation (which you are probably already using) and in most of the cases will only result in another level of indirection into StdLine but that will prevent your program from calling QuickDraw with parameters that are guaranteed to cause crashes.
Use crsrNew flag to unobscure cursor without mouse move
Date Written: 3/3/92
Last reviewed: 6/14/93
The Macintosh QuickDraw routine ObscureCursor hides the cursor until the next time the mouse is moved, but it isn’t affected by HideCursor or ShowCursor. Our application needs to use ObscureCursor while the user is typing but needs the cursor to be visible after no typing has occurred for a short period. How do we “undo” ObscureCursor, since we can’t rely on the user to move the mouse?
___
The only way (besides actual mouse movement) to make an obscured cursor visible again is to convince the system that the mouse has moved. There’s no really good way to do this via Toolbox calls, so you’re going to have to do it the hard way and simply update the low-memory cursor information to tell the system the cursor moved (even though you don’t need to update the actual position).
To tell the system the cursor has changed location, simply set the crsrNew flag (a byte located at $08CE) to 1. When the system sees this byte is 1, it will assume the cursor has moved and redraw the unobscured cursor at the appropriate place (where it was all along), and reset CrsrNew, waiting for the mouse to move again.
Macintosh CalcMask and CopyMask code sample
Date Written: 2/27/92
Last reviewed: 6/14/93
I can’t get the black-and-white version of my lasso-type tool to work correctly with CalcMask and CopyMask. With CalcCMask it seems to work fine. What could I be doing wrong?
___
CalcMask and CalcCMask are similar in that they both generate a 1-bit mask given a source bitmap. With CalcCMask, though, a pixMap can be used in place of the source bitmap; the seedRGB determines which color sets the bits in the mask image. An easy mistake to make is to forget that CalcCMask accepts a pointer to a bitmap data structure while CalcMask expects a pointer to the actual bit image. And unlike CalcCMask, which uses bounding Rects for the image’s dimensions, CalcMask uses the bitmap’s rowBytes and pixel image offsets to determine the bounding Rects for the image. A typical call to these routines would be
One last thing to note when using CalcMask is that the width of the image is in words and not bytes. To learn more about these routines, see page 24 of Inside Macintosh Volume IV and page 72 of Inside Macintosh Volume V. Also, the Developer CD Series disc contains a sample, CalcCMask&CalcMask, that shows how to use both these routines.
Code for filling an area fully bounded by polygon
Date Written: 2/21/92
Last reviewed: 6/14/93
Currently, when a polygon is filled, an even-odd rule is applied to determine which areas of the polygon are to be filled. For our application, we also need to fill all the areas of the defined polygon. Is there a relatively easy way to accomplish this?
___
There are many different ways to fill polygons, as you may know. If you do not want to use QuickDraw’s standard FillPoly routine, you’ll have to create your own. The following sample illustrates one technique that might be used to fill the area fully bounded by a polygon. It can be dropped right into the traffic light sample (sample.p) that ships with MPW as a replacement for its DrawWindow procedure. The green star is drawn using FillPoly and the black star is drawn using my filling technique that uses an offscreen bitmap and calcMask to fill in the poly the desired way, then CopyBits to transfer it to the onscreen port. The drawbacks of this method are that it is not as fast as writing a specialized poly routine; the benefits are that it’s small, fast enough for most operations, and can be used for more than just polygons.
{$S Main}
PROCEDURE DrawWindow(window: WindowPtr);
var MyPoly:PolyHandle;
MyRgn :RgnHandle;
OffPort,OnPort:GrafPtr;
Function CreateOffport(VAR newOffscreen:grafPtr;
inBounds:Rect):Boolean;
var SavePort,NewPort:Grafptr;
begin
GetPort(SavePort);
NewPort:=GrafPtr(NewPtr(sizeof(grafport)));
If MemError<>noErr then Begin
CreateOffport:=false;
EXIT(CreateOffport);
END;
OpenPort(newPort);
With newPort^ do begin
portRect :=Inbounds;
RectRgn(ClipRgn,inBounds);
RectRgn(visRgn, inBounds);
End;
With newPort^.PortBits DO BEGIN
Bounds:=Inbounds;
rowBytes:= ((inBounds.right-inBounds.Left+15) DIV 16) *2;
baseAddr:= NewPtr(rowBytes
* LONGINT(inBounds.Bottom-inBounds.Top));
End;
If MemError <>noErr THEN BEGIN
SetPort(SavePort);
ClosePort(newPort);
DisposPtr(ptr(newPort));
CreateOffport:=false;
END
ELSE BEGIN
EraseRect(inBounds);
newOffscreen :=newPort;
setPort(SavePort);
CreateOffPort:=true;
end;
end;
Procedure KillOffPort(oldOffscreen :GrafPtr);
Begin
ClosePort(oldOffscreen);
DisposPtr(OldOffscreen^.portBits.baseAddr);
DisposPtr(ptr(OldOffScreen));
End;
BEGIN
If NOT (CreateOffPort(offPort,window^.portRect)) THEN Exit(DrawWindow);
If NOT (CreateOffPort(onPort,window^.portRect)) THEN Exit(DrawWindow);
Inside Macintosh Vol. V PICT opcode size should be fixed
Date Written: 1/22/92
Last reviewed: 2/28/92
The definition of PICT version 2 on pages 92-105 of Inside Macintosh Volume V says that the data size of the opcodes $001A and $001B is variable, but also that the data is an RGBColor. This is confusing, since the size of an RGBColor is fixed at six bytes. How can these two opcodes vary in the amount of associated data?
___
Seems like you’ve run into a cut/paste problem. All the opcodes that refer to table 4 are new for Color QuickDraw. Also, most of them are variable in length, so the author simply had a standard notation for anything that was explained further in table 4 (page V-103). The information contained in table 4 is, in fact, accurate. The size information of several of the opcodes listed is not variable even though the preceding pages told you they were.
All you gotta do is believe table 4 and you will be fine.
PICTs with PostScript PICT comments and memory use
Date Written: 1/10/92
Last reviewed: 6/14/93
Why does my PICT (including dotted lines) use so much memory when drawn in MacDraw, and even more when drawn in SuperPaint? Do they include PicComments for PostScript?
___
Your guess that it has to do with PicComments is quite right; both MacDraw and SuperPaint include a PostScript representation of the dotted (dashed) lines and some other graphic operations in the PICT, together with the QuickDraw commands. During printing, this allows the LaserWriter driver to take advantage of specific PostScript capabilities that are unavailable in QuickDraw, like primitives for dashed lines.
On the other hand, the PostScript representation for dashed lines is much shorter than the QuickDraw representation, which requires a (long, very long …) sequence of “ShortLine” opcodes. So, another piece of explanation for the large PICT size basically is that QuickDraw does not have facilities to describe dotted lines in an economic way.
SuperPaint also includes a copy of a proprietary dictionary, which adds substantially to the size of a PICT. On the other hand, the code that resides in that dictionary makes the picture’s PostScript representation that much better. Ultimately, WYSIWYG is the goal, and sometimes it takes a little extra code to make that happen. (Incidentally, the PostScript dictionary contained in pictures created by older versions of SuperPaint makes assumptions about the contents of the LaserPrep file which are not true for the recent versions of the LaserWriter driver. Documents containing such pictures will not print correctly any more.)
To determine the primitives that define other nonstandard QuickDraw objects found in drawing applications, you can use MPW’s DeRez function or a third-party utility such as Palomar Software’s PICT Detective on the resource PICT. These tools will provide the opcodes that define the PICT.
Where CopyBits looks for memory to use
Date Written: 1/3/92
Last reviewed: 1/27/92
Where does CopyBits look for the memory it needs?
___
CopyBits checks the stack to determine if there is enough stack space for it to copy the whole image, which in some cases may be roughly up to 5 extra rowbytes of special effects per row, depending on what special effects such as dithering or scaling are being used. If there is not enough stack space for the whole image, CopyBits then tries for half the image, and keeps halving until it gets down to one row of the image (plus the room for the special effects rows). If there is not enough stack space for one row of the image, then CopyBits tries to allocate temporary memory.
Before allocating temporary memory, CopyBits checks if the temporary memory traps are available. (They are available under both System 6 MultiFinder and System 7.) If the traps are available, CopyBits tries to allocate a 256K byte buffer for use as a “fake” stack. (CopyBits used to try for a 64K block, but this has been changed, and it may change again.) If this succeeds, then all is well and the image is copied. If the temporary memory traps do not exist, or if CopyBits cannot allocate a 256K buffer, then the image is not copied and CopyBits returns.
CopyBits does not check in the application heap for free memory, at least not for its work buffer. For its work buffer it will only use the stack, and after that it resorts to temporary memory, if available. There are some circumstances that may cause memory allocations in the application heap, but this memory is not used for CopyBits’s image buffer.
Also, please note that the implementation of CopyBits is subject to change in future versions of QuickDraw.
GrafPort patStretch: valid values
Date Written: 12/19/91
Last reviewed: 6/14/93
I’d like to know more about that PatStretch field inside a GrafPort or CGrafPort. If I stuff a values in PatStretch(4) then nothing happens; prints look the same, even using a standard bottleneck. Please tell me how I can get this to work.
___
PatStretch only works with values of 2 or 3. With any other value, it defaults to no stretching. The “2” case was created because of the ImageWriter (72->144 dpi) situation. The “3” case was added to support the ImageWriter LQ and the AppleFax modem.
So why wasn’t a “4” (72->300 dpi) handler added for the LaserWriter driver? Good question. Somehow or other it was decided that pattern stretching for the LaserWriter driver would be done completely by the driver itself. The LaserWriter driver actually does pattern stretching by using a pattern 4 times as large, rather than 4.17. In other words, it really scales the 72 dpi pattern to 288 dpi rather than 300 dpi. You may want to take a similar approach, since you’d only have to work with whole numbers this way.
So, if you want to do 4-times pattern stretching, you must scale the pattern yourself. If you copy the original pattern into an area that’s twice as wide and twice as tall and use that, you should be all set. You’ll need to use PrGeneral to set the printer to the appropriate resolution and Copybits to copy the pattern into the object that needs to be filled, using the “cookie cutter” approach to fill the object.
X-Ref:
Inside Macintosh Volume I, page I-150
How to tell whether GetPictInfo is available
Date Written: 12/16/91
Last reviewed: 6/14/93
How do you determine whether the Picture Utilities Package function GetPictInfo is available? Gestalt doesn’t seem to have the right stuff!
___
To determine whether the GetPictInfo routine is available, check the system version number with the Gestalt function. GetPictInfo is available in system software version 7.0 and later. Use the Gestalt selector gestaltSystemVersion to determine the version of the system currently running. Usually it’s best not to rely on the system version to determine whether features are available, but in this case, it’s the only way to determine whether the Picture Utilities Package is available.
For example, the following C function will determine whether the GetPictInfo call is available:
#include <GestaltEQU.h>
Boolean IsGetPictInfoAvail()
{
OSErr err;
long feature;
err = Gestalt(gestaltSystemVersion,&feature);
/* Check for System 7 and later */
return (feature >= 0x00000700);
}
In Inside Macintosh Volume VI, see page 3-42 for information on using Gestalt to check the system version number, and see page 18-3 for information on the Picture Utilities Package.
Detecting whether application window is partially hidden
Date Written: 9/26/92
Last reviewed: 6/14/93
We draw directly to the screen to gain the fastest possible animation speed, and when we need compatibility—such as when windows overlap or for multiple screens—we do use CopyBits. How do we tell whether the window is hidden or that the visible part is not rectangular?
___
If your window is covered partially by another applications window or if your layer has been hidden by the process menu, the visRgn of your window’s grafport will not be the portRect anymore. (Keep in mind that if you scroll by modifying the portRect of the grafport, then you’ll have to do a more complex calculation...) Here is a small Pascal routine that returns this information:
Function UseCopyBits(thePort:grafptr):Boolean;
begin
UseCopyBits:= NOT( (thePort^.VisRgn^^.rgnSize=10) and
(thePort^.visRgn^^.RgnBBox=thePort^.PortRect) );
end;
The rect strucRgn^^.rgnBBox will be zero for a visible window if the system
has hidden the application.
CopyBits bug and workaround
Date Written: 6/26/91
Last reviewed: 6/14/93
Has anyone run across what I’m told is a bug in CopyBits? It works like this: In the deep, dark workings of CopyBits, some routine tries to read the two bytes preceding the baseAddress of the source PixMap. If the baseAddress is at the start of a card’s NuBus space and there isn’t a card filling the adjacent space, this causes a bus error! Has anyone found a good workaround?
___
The short answer is: you’re right. QuickDraw inadvertently reads from memory below the base address of a pixmap. The workaround is to place the video base address 32 bytes into the slot memory space for the card; if the card you’re using doesn’t have this workaround, there’s nothing you can do other than making sure there’s a card in the next-lower slot.
Macintosh animation samples
Date Written: 11/6/91
Last reviewed: 6/14/93
Do you have an example of flicker-free animation on the Macintosh?
___
We have some good stuff that’s written in MPW Pascal. It’s DTS Sample Code #16, OffSample, and this uses some routines defined in DTS Sample Code #15, OffScreen. Also, the System 7.0 CD sample code folder contains a smaller sample called “GMonde” that uses GWorlds.
System 7 QuickDraw DrawText performance
Date Written: 11/4/91
Last reviewed: 11/27/91
We’ve noticed that using DrawText is much slower in System 7, especially when drawing in color (anything other than black on white). What can be done to restore the drawing speed to System 6 levels?
___
A QuickDraw function like DrawString or DrawText will be slower under certain circumstances in System 7 than System 6. Specifically, if you are drawing in srcCopy mode and you colorize the text—that is, foreground color is not black and background color is not white (Inside Macintosh Volume VI, page 17-16)—then QuickDraw really slows down as you have noticed. Sometimes, the speed of drawing is 6 times as slow as System 6.
The cause of this slowness is a known System 7 bug. The bug has concerned the engineers greatly and will be responded to in an appropriate manner in the future.
There are a few workarounds: One, you can avoid using the srcCopy mode and use the default srcOr mode instead. However, this is not a real workaround, since you may have essential reasons to use srcCopy. The other option is to create an offscreen pixmap or GWorld and perform a DrawText with srcOr to this GWorld with colorization. Then, you can perform a CopyBits from the offscreen to the screen with srcCopy mode and no colorization. Using CopyBits will not cost you much time. Again, this is a workaround and is not ideal.
The srcOr is a bit slower than in System 6.0.x, but it does not have a bug; rather it is a side effect of system enhancements. The slow speed is a trade-off taken to receive the host of other benefits.
Updating Macintosh cursor without mouse competition
Date Written: 6/12/91
Last reviewed: 6/14/93
How can I programmatically move the Macintosh mouse without the real mouse interfering?
___
The real answer to your question is twofold: First, you can do exactly what you want to do with the sample included below. However, this is not a good thing to do, it would be better if you took the solution used in Apple’s Guided Tour disks: Always hide the cursor and then decouple the cursor from the mouse. Then, instead of using the system’s cursor, simply draw your own “cursor” using QuickDraw and treat it as a little animated bitmap on the screen. This avoids all the problems that you have with the mouse competing. (Apple does update the mouse globals with the mouse position so that other things function correctly.)
Now, as promised, here is the way to do what you want using the real cursor. As you have discovered, setting the crsrCouple variable to false prohibits the mouse from affecting the cursor; unfortunately, it also prohibits the jcrsrTask routine from drawing the cursor. The solution to this is to set crsr couple to true, call the cursor drawing routine jCrsrTask yourself, and then set the crsrCouple variable to false, as shown below:
procedure callcrsr;
inline $2078 ,$08EE ,$4E90;
{ move.L jcrsrTask,A0
jsr (A0) }
Procedure FudgeMouse;
type PointPtr=^Point;
var RawMouse:PointPtr;
MTemp:PointPtr;
RandPt:Point;
CrsrNew:ptr;
CrsrCouple:ptr;
fred:Longint;
begin
RawMouse:=PointPtr($82C);
MTemp:=PointPtr($828);
CrsrNew:=ptr($8CE);
CrsrCouple:=ptr($8CF);
RandPt:=RawMouse^;
repeat
RandPt.h:=RandPt.h+1;
RandPt.V:=RandPt.v+1;
RawMouse^:=RandPt;
MTemp^:=RandPt;
CrsrNew^:=1;
CrsrCouple^:=1;
callCrsr;
crsrCouple^:=0;
repeat until fred<tickCount;
fred:=tickCount+3;
until Button;
crsrCouple^:=1;
end;
Techniques for graying Macintosh text
Date Written: 6/3/91
Last reviewed: 6/14/93
How do I draw grayed-out text on the Macintosh, like the text for disabled buttons or menu items?
___
There are currently two different kinds of grayed text: First, there’s “patterned” gray, where every other dot is missing. This really only looks good with Chicago or other heavy fonts and was always used for graying out menus and controls in system software through 6.0.x, and is still used in 7.0 when the screen is set to less than 4 bits deep. This is done by first drawing the text in a normal, srcCopy transfer mode. Then a gray rectangle is drawn over the text using the patBic mode. This “erases” half the bits in the text, and is rapid enough that there is very rarely any flicker.
The second kind of text is the actually gray text, which is used in System 7 on screens that are 4 bits deep or deeper for menus, controls, and other grayed text. To draw this text, just call GetGray (as documented on page 17-27 of Inside Macintosh Volume VI) to get an appropriate gray. Then draw the text in that color.
Use srcOr instead of srcCopy for Macintosh text drawing
Date Written: 6/4/91
Last reviewed: 10/9/91
DrawText with srcCopy takes six times as long as with srcOr now that my Macintosh is running System 7. Why is this so slow? Is this a bug in System 7?
___
It’s true that srcCopy is slower than srcOr when handling text, especially in color mode. This loss in speed occurs because CopyBits is a lot smarter than it used to be. It can handle foreground and background colors a lot better, but that improvement came at the cost of speed. Our recommended method for drawing text is to erase before drawing, and use srcOr to draw, not srcCopy. Alternatively, you could draw colorized text in srcOr mode off screen and then use CopyBits to draw it on the screen in srcCopy mode without colorization.
Code for reversing Macintosh PICT images
Date Written: 3/4/91
Last reviewed: 6/14/93
Is there a simple way to put PICT images up in mirror image format, or is there sample code showing how to flip an offscreen bitmap?
___
There is no easy way to do this, nor do we have sample code showing how to flip an offscreen bitmap. Indeed, the best way to do what you want is to draw it to an offscreen pixel map and reverse it.
If you are using Color QuickDraw, always draw it to an 8-bit-per-pixel offscreen bitmap, and then the reverse is a very simple task. Here is some sample Pascal code that might roughly do what you want, with the following assumptions:
1. You are going to add error checking where appropriate.
2. Rowbytes correspond exactly to pixel width of the port.
{ The scan line is simply an array [0..RowBytes] of Byte, and since this is }
{ 8 bits per pixel, each one is a single pixel.}
Size:=thePixMap^.RowBytes;
For Index:=0 to (Size div 2) do
begin
tempPixel:=ThisScanLine^[Index];
ThisScanLine^[Index]:=ThisScanLine[Size-Index-1];
ThisScanLine^[Index]:=tempPixel;
end;
end;
This same procedure can be used also to swap a 1-, 2- or 4-bit-per-pixel pixmap if you add a function that accepts a byte and swaps the pixels in it.
Using dithered drawing mode with QuickDraw
Date Written: 11/28/90
Last reviewed: 12/19/90
When I draw a 32-bit Macintosh PICT image from a file to an 8-bit port via an offscreen GWorld, I use dither mode in the CopyBits call and the results are quite impressive. If there is not enough memory to allocate the GWorld, I draw the image directly to the port. But since there does not seem to be any way to tell QuickDraw to use dithered drawing mode, the image looks horrible.
Do you have any suggestions? I have installed bottleneck procs to allow DrawPicture to get its data from the file instead of the handle in memory. Is there a way, while in the bottlenecks, to find the CopyBits call that comes from the picture and force it to use dithered mode instead of source mode? I don’t want to try and parse the PICT myself, but I thought that maybe a QuickDraw global could be modified in my StdBits proc to force dithered drawing for that operation only?
___
You can install a StdBits or bitsProc bottleneck procedure to get all the CopyBits calls when the picture is being played back. One of the parameters to the StdBits call is the mode. You can install a procedure that saves the current mode, and then passes ditherMode to the original StdBits proc. This is all you should need to do. It’s been done here so we know it works, only not in any form that can be sent to you as sample code at this time.
Using PicComments to rotate text
Date Written: 11/28/90
Last reviewed: 12/19/90
I have a PostScript routine (using TextBegin/TextEnd) to generate bitmapped rotated text on the screen (which can be later printed on QuickDraw printers). Why do I get duplicate text? I get both bitmapped rotated text and PostScript rotated text when I print on the LaserWriter II, and both bitmapped rotated text and horizontal text on the ImageWriter. When I make a machine dependent check (check type of printer) and call the proper printing procedure, it works fine. Because of the speed and memory considerations of generating the rotated bitmapped text (especially at 300 dpi), is there a way to ensure that the printer will use the PostScript BEFORE generating the bitmap?
___
We will use the following Macintosh PicComments to hide your QuickDraw calls from the LaserWriter, but the ImageWriter will use them:
PostScriptBegin
>> Put your CopyBits and QuickDraw calls to image your rotated
>> bitmapped text here....
PostScriptEnd
By wrapping your QuickDraw code within the PostScriptBegin and PostScriptEnd PicComments, the code will be ignored by the LaserWriter, but the ImageWriter will use the QuickDraw calls. Basically, the PostScriptBegin and PostScriptEnd PicComments tell the LaserWriter driver to turn “off” QuickDraw. In the ImageWriter case, the ImageWriter does not understand the PicComments. Therefore, it will use the QuickDraw calls to create and image your bitmapped text.
Now, we need to use the rotation PicComments to rotate the text on the LaserWriter, but have the ImageWriter ignore the code:
Rect zeroRect;
SetRect (&zeroRect, 0, 0, 0, 0);
TextBegin
TextCenter
ClipRect (&zeroRect);
>> Draw your text to be rotated on the LaserWriter....
ClipRect (&rPageRect);
TextEnd
Wrapping your text drawing call(s) between the ClipRect calls will ensure that the text is drawn only on the LaserWriter. Setting the ClipRect to zero tells the ImageWriter to ignore all QuickDraw calls until the ClipRect is reset to something “real” (actually, a zero ClipRect prevents QuickDraw from drawing anything). After we have completed drawing the rotated text, we reset the ClipRect to the dimensions of rPage (that is, rPage is the image-able area of the currently selected printer—see Inside Macintosh Volume II, page 150). This will allow all of your normal drawing to continue on the ImageWriter and LaserWriter. If you did not reset the ClipRect after the TextEnd call, nothing would be drawn on the ImageWriter or LaserWriter.
Why grafPort’s clipRgn should be changed before OpenPicture
Date Written: 11/1/90
Last reviewed: 12/19/90
On page 189 of Inside Macintosh Volume I, in the QuickDraw chapter’s description of OpenPicture, is the following warning: “A grafPort's clipRgn is initialized to an arbitrarily large region. You should always change the clipRgn to a smaller region before calling OpenPicture, or no drawing may occur when you call DrawPicture.” The “arbitrarily large” clipping region rectangle is set to -32767,- 32767,32767,32767 (top, left, bottom, right) for new ports. This is the largest rectangle possible. If this is not a "valid" clipping rectangle for pictures, what is? Is there some specific limit to the size of the clipping rectangle? Does it depend on either available memory or the size of the picture?
___
Inside Macintosh’s warning is based on truth but it’s incomplete. It didn’t actually say that this rectangle is invalid as a clipping region, because this is in fact a perfectly valid clipping region. But, you could run into problems if you use this as a clipping region when creating a QuickDraw picture. It’s not a matter of available memory or size; it’s a simple matter of 16-bit signed integer overflow and underflow.
When you open a picture, the current clip region is recorded in the picture (this wasn’t necessarily true in some early versions of QuickDraw). When you draw the resulting picture using the picture’s picFrame as the destination rectangle, there won’t be any problems. But if you use a destination rectangle that’s larger than the picFrame, QuickDraw scales everything in the picture proportionately, including the clip region. If you allowed the default clip region to be recorded into the picture, then its rgnBBox, already as large as possible, will be made even larger. That means that the -32767 coordinates might wrap around to the positive number range, and the 32767 coordinates might wrap around to the negative number range. This leaves you with an empty clip region. Nothing at all gets drawn when the current port’s clip region is empty.
If the destination rectangle is smaller than the picture’s picFrame, you won’t have any problems because the default clip region will be made smaller, and that’s no problem.
This is why Inside Macintosh suggests that you make the clip region smaller than the default clip region before opening a picture. By doing this, you’re almost guaranteed that the clip region won’t get scaled to the point that it turns inside out. What size should you make it? Small enough so that the risk of the clip region’s coordinates being scaled out of QuickDraw coordinate space is minimal. I usually just set the clip region to the picFrame of the picture. It’s hard to go wrong this way.
Calling InitCursor instead of SetCursor
Date Written: 10/23/90
Last reviewed: 6/14/93
Is it legal to call InitCursor instead of SetCursor(arrow) when I want to set the cursor to an arrow (after my normal one-time program initialization code, in my UpdateCursor routine)? The only reason I'd want to do such a skanky thing is to save code. Calling a trap with no parameters is less code than one with parameters. What, exactly, if anything, does InitCursor do besides setting the cursor to an arrow and setting the cursor level to zero?
___
There's no problem at all with this, as long as you are aware that the hidden, busy, and obscured states are cleared when you call InitCursor, so if the cursor was hidden or obscured for good reason it'll suddenly reappear. It also gets the arrow from QuickDraw, of course, but that's not a problem.
Macintosh PICT-to-PostScript conversion
Date Written: 8/3/90
Last reviewed: 10/8/91
How do I convert PICT format data to PostScript in my printer driver?
___
Converting PICT files to PostScript involves a detailed understanding of both bitmaps (or pixmaps) and the graphics state in PostScript, which is a data structure defining the context in which other graphic operators in PostScript execute. If you don’t know PostScript, the following manuals are a must:
• PostScript Language Tutorial and Cookbook (Addison-Wesley) is an introduction to PostScript. • PostScript Language Reference Manual (Addison-Wesley).
• PostScript Language Program Design (Addison-Wesley) details designing efficient PostScript programs. It has a lot of useful sample programs on topics like writing a print spooler.
You need to convert all the QuickDraw operations in a PICT to corresponding PostScript operations. To get a feel for this conversion, you can analyze the PostScript dump from a LaserWriter to see how it converts a PICT to PostScript. Under System 6.x, a PostScript dump can be obtained by pressing Command-K while printing. Under System 7.0, you can get a dump by selecting the PostScript File option in the Print dialog.
Some areas of QuickDraw, such as transfer modes, do not have a correspondence in PostScript. The PostScript imaging model is designed so that all areas of a page affected by an image are marked as if with opaque paint. Using image masks can help. See the Graphics chapter in the PostScript reference manual.
PICT-to-PostScript conversion can be a long process, especially if one is unfamiliar with PostScript. Using the above books and the PostScript dump from the LaserWriter (but ONLY as a general guide) should help.
Sending PostScript via PostScriptHandle PicComment
Date Written: 5/1/90
Last reviewed: 10/9/91
If I use the PostScriptHandle PicComment to send PostScript code to the LaserWriter driver, do I need to open a picture and then draw the picture to the driver, or can I just use the PicComment with no picture open while drawing to the printer’s grafPort?
___
You don’t need to create a picture with your PicComment in it and draw the picture to the driver. The best method for sending PostScript code to the LaserWriter is to use the PostScriptHandle PicComment documented in the Macintosh Technical Note “Optimizing for the LaserWriter—Picture Comments,” as shown below.
PrOpenPage(...)
{ Send some QuickDraw so that the Printing Manager gets a }
The above code prints a line on any type of printer, PostScript or not. The first MoveTo/LineTo combination is required to give the LaserWriter driver a chance to define a clipping region. The LaserWriter driver replaces the grafProcs record in the grafPort returned from PrOpenDoc. In order for the LaserWriter driver to get execution time, you must execute a QuickDraw drawing routine that calls one of the grafProcs. In this case, the MoveTo/LineTo combination calls the StdLine grafProc. When StdLine executes, it notices that the grafPort has been reinitialized, and therefore initializes the clipping region for the port. Until the MoveTo/LineTo combination is executed, the clipping region for the port is set to (0,0,0,0). If PostScript code is sent via the PostScriptHandle PicComment before executing any QuickDraw routines, all PostScript operations will be clipped to (0,0,0,0).
The next thing that’s done is to send the PostScriptBegin PicComment. This comment is recognized only by PostScript printer drivers. When the driver receives this comment, it saves the current state of the PostScript device (by executing the PostScript gsave operator), then disables all QuickDraw drawing operations. This way, the QuickDraw representation of the graphic will be ignored by PostScript devices. In the above example, the second MoveTo/LineTo combination is executed only on non-PostScript devices.
The next PicComment is PostScriptHandle, which tells the driver that the data in thePSHandle is to be sent to the device as PostScript code. The driver then passes this code unchanged to the PostScript device for execution. The PostScriptHandle comment is recognized only by PostScript printer drivers.
The last PicComment, PostScriptEnd, tells the driver to restore the previous state of the device (via a PostScript grestore call), and to enable QuickDraw drawing operations.
Since most PicComments are ignored by QuickDraw devices, only the QuickDraw representation is printed. Since PostScriptBegin tells PostScript drivers to ignore QuickDraw operations, only the PostScript representation is printed on PostScript devices. This is a truly device-independent method for providing both PostScript and QuickDraw representations of a document.
Macintosh QuickDraw region quirks
Date Written: 1/1/90
Last reviewed: 11/21/90
I’m working with regions, and I’m having problems with Macintosh QuickDraw trashing the heap and crashing, even though my regions are under 32K.
___
There are some quirks in the current version of QuickDraw. Here are some the commonly-encountered problems:
1. When doing operations which use more than one region, sduch as UnionRgn, DiffRgn, XorRgn, or SectRgn, the sum of the sizes of the source regions must be less than 32K, regardless of the size of the resulting region.
2. FrameRgn will fail if it tries to frame a region bigger than 16K.
3. If CloseRgn fails, the internal region data is already corrupt; there is nothing you can do to recover. CloseRgn will also fail if there isn’t at least a 32K block of free space available.
Here are some workarounds:
1. Keep regions small and not too complex. Keep track of the sizes of all regions so you can check the SUM of the sizes before calling a routine that has a 32K limit.
2. Keep 32K free, or allocate a 32K block and release it just before calling CloseRgn.
Apple is working on these problems and expects to fix them in future versions of QuickDraw.
How to get Macintosh QuickDraw arc endpoints
Date Written: 1/1/90
Last reviewed: 6/14/93
Is there a way to obtain the endpoints of an arc drawn by the Macintosh QuickDraw arc routines, such as FrameArc and PaintArc?
___
Given a rectangle R which frames the arc you wish to draw, convert your angles to an absolute coordinate system, where three o’clock is 0 degrees and 12 o’clock is 90 degrees.
Now, let:
x = .5 (+ or -) (R.right - R.left)
y = .5 (+ or -) (R.bottom - R.top)
The endpoint of the curve will be defined by:
EndPoint.h = x (+ or -) cos(ang);
EndPoint.v = y (+ or -) sin(ang);
h & v are relative to center of rectangle R
This calculates only the upper endpoint of the arc, but you can easily calculate the other endpoint using the same formula by calculating the absolute angle for the start point and applying the same formula.
Here is a subroutine which illustrates the algorithm, in ThinkSpeed Pascal:
{ DrawCurve: draw an arc from 0 degrees until the point defined }
{ by 'angle'. At that point draw a 4 by 4 crosshair. }
x := (frame.right + frame.left) / 2 + Num2Integer(xr);
y := (frame.bottom + frame.top) / 2 + Num2Integer(yr);
{ Draw crosshair }
MoveTo(x - 4, y);
LineTo(x + 4, y);
MoveTo(x, y - 4);
LineTo(x, y + 4);
{ Draw arc }
FrameArc(frame, 0, angle);
end;
QD 510 - Color Manager Q&As
QuickDraw
Revised by: Developer Support Center September 1993
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
Using ResEdit to get Apple icon RGB values
Date Written: 1/7/92
Last reviewed: 6/14/93
I am trying to find the RGB values for Apple's standard icon colors. I can’t find this information in any documentation. Is this information available?
___
While the RGB values for the standard Apple icon colors (and other standard palette colors) are not explicitly documented, they are easy to obtain with ResEdit 2.1.1. In any resource file, create and open a new 'pltt' resource. Choose Load Colors from the pltt menu and pick Apple Icon Colors, and a standard palette will be created. Selecting a color will reveal its component values.
ResEdit 2.1.1 is available on the latest Developer CD Series disc and from APDA.
Macintosh Color Manager versus Palette Manager
Date Written: 1/1/90
Last reviewed: 6/14/93
When should the Macintosh Color Manager be used and when should the Palette Manager be used?
___
The Palette Manager is by far the friendlier and more versatile of the two if your application uses different colors than the default system colors. It provides all the functionality you need to customize and animate the colors in your application. You shouldn’t ever need to use the Color Manager unless you require custom color search and complement functions. When using the Palette Manager, applications will maintain their respective color environments safely as they move back and forth from foreground to background, and from one screen to another. Accomplishing this with the Color Manager calls is not worth the effort or very safe. For additional information, see the Palette Manager chapter in Inside Macintosh Volumes V and VI.
QD 515 - Color QuickDraw Q&As
QuickDraw
Revised by: Developer Support Center September 1993
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As in this Technical Note:
Color QuickDraw not available to 68000 Macintosh models
Check ‘cicn’ ID if menu icons are tiny
Color QuickDraw and large pixmaps
Color QuickDraw not available to 68000 Macintosh models
Date Written: 2/4/93
Last reviewed: 3/17/93
Inside Macintosh Volume VI says Color QuickDraw is built into System 7, but when I use Gestalt to check for Color QuickDraw on a Macintosh PowerBook 100 running System 7, the call returns 0 in QDversion. What’s wrong?
___
The Color QuickDraw routines were written in 68020 assembly, meaning that only Macintosh models with 68020 and later CPUs have access to Color QuickDraw. Models such as the Macintosh SE, Macintosh Classic, and PowerBook 100 can use only Classic QuickDraw. However, this isn’t such a bad thing because the processing power required to run Color QuickDraw would be an enormous burden on the 68000 machines.
The bulk of Color QuickDraw routines reside in the larger ROMs of models using the 68020 and greater CPUs, thus taking the burden away from system software. However, if changes have to be made to Color QuickDraw (usually in the form of patches) they reside in system software.
Check 'cicn' ID if menu icons are tiny
Date Written: 2/16/93
Last reviewed: 7/2/93
The icons that appear in our application’s menu lists are very, very small. It looks like they’re 8 x 8 (scaled) instead of the standard 16 x 16. Can you tell from our test code why this is happening?
___
This was a wild one! What’s causing the weird behavior is that you have a 'cicn' resource with ID = 256 that’s smaller than 32 x 32. When the MDEF finds such an icon, it uses it to size the area to use for the menu icons. So, for your application the solution is either to change the 'cicn' to be larger (32 x 32) or to give it a different ID.
Color QuickDraw and large pixmaps
Date Written: 3/11/93
Last reviewed: 6/24/93
Somewhere in QuickDraw, a routine is using the 14th bit of the rowBytes field (the 15th is used to differentiate a pixmap from a bitmap) and it really shouldn’t. This is a problem now that it’s so easy to create large pixmaps of 4096 32-bit pixels or more. What’s causing the problem and what’s the recommended solution for handling large pixmaps?
___
This is a long story. It’s described in Inside Macintosh Volumes V and VI but we’ll summarize it here.
Color QuickDraw allows you to pass one of three addresses to CopyBits: the address of a bitmap, the address of a pixmap, or the address of the pixmap handle of a port. The first two conditions (bit and pixmap) are determined by bit 15 of rowBytes: if the bit isn’t set, the address points to a bitmap; otherwise, it points to a pixmap. The third case is the problem here. A color port’s portVersion field is expected to be set to 0xC000, so after deciding it’s dealing with a possible pixmap CopyBits checks bit 14 and if it’s set it assumes it got the address of the pixmap handle in a CGrafPort and proceeds to dereference it in order to get the real address of the pixmap.
Today’s applications have trouble with this because they must either refuse to create pixmaps as big as users want or cause crashes by confusing CopyBits into dereferencing the base address of the pixmap if rowBytes exceeds the established limit of less than 0x4000.
Engineering is studying future solutions. It’s possible that a future QuickDraw release will support pixmap with a rowBytes constant value indicating that the real rowBytes is contained in the planeBytes field instead. You might think of cases where this is also going to cause problems but the problems probably are less important than the limitation being overcome.
For the present, the solution depends on the conditions under which the problem affects you. If you’re writing an application, the solution could be to patch CopyBits and call DrawPicture. When CopyBits is called while a picture is being drawn the source is a pixmap; if rowBytes is too big, your application could split the job banding the image vertically until the resulting rowBytes values fall within range. With a little debugging it would be possible to find where CopyBits calls the bit/pixmap/port checking routine and bypass that, given that the actual routine doing the blitting doesn’t have problems dealing with pixmaps of less than 0x8000 rowBytes.
Another possibility is to call StdBits directly since it doesn’t mind dealing with larger than legal rowBytes. The problem here is that the destination is implied and the application has to make sure that everything is all right. Also if the destination spans multiple devices the application must divide the task, targeting each device at the time. See the DeviceLoop procedure in Inside Macintosh Volume VI for ideas on this.
To recap: The limitation of rowBytes is becoming increasingly painful, now that applications can easily create pixmaps (and PICTs) that exceed the limit of 0x4000. It’s possible for an application to patch CopyBits in order to work around this limitation but you have to decide what is appropriate for each set of conditions.
Animation speed on the Macintosh
Date written: 1/18/93
Last reviewed: 4/1/93
How can I get reasonably fast animation on Macintosh models? So far, I’ve created off-screen pixmaps with the image and mask, and an extra off-screen pixmap for use in restoring the original picture. However, CopyPix is still too slow. I had to write my own CopyPix routine in assembly, which works great. But I can’t help wondering how Apple expected fast animation to be accomplished.
___
You’re certainly right that the way to increase performance is by off-screen drawing and QuickDraw’s CopyBits procedure. The key information that’s useful to you is in the Macintosh Technical Note “Of Time and Space and _CopyBits.” This tech note covers some of the factors affecting CopyBits and what can be done to improve the speed of calling CopyBits.
Just to mention some of the factors that might improve the speed of calling CopyBits: Avoid color mapping, or even try faking out color mapping by setting your ctSeed to be the same. Alignment of pixels in the source map relative to their alignment to the destination pixel map can be important. If the source and destination rectangles are different sizes, CopyBits has to scale the copied image, which slows it down a lot. Also dithering and bit depth has effect on the speed of CopyBits.
Whereas QuickDraw often trades performance for flexibility, there are times we’d just as soon trade flexibility for performance. In these cases, we can achieve tremendous gains in speed by writing custom routines to draw to off-screen worlds. I recommend the article “Drawing in GWorlds for speed and versatility” (develop, issue 10) which shows you exactly how to do that.
Many developers want to go beyond the speed of QuickDraw. Writing directly to the screen can allow you to create faster animation and graphics than possible with QuickDraw. However, Apple has always maintained that writing to video memory is unsupported, since it may cause your application to break on future systems. If you write directly to the screen, your application will forfeit the use of many Toolbox managers and will put future compatibility at risk. Since most applications require the Window Manager and other basic Macintosh managers, writing to the screen is for only a few specialized applications, such as video games and some animation packages that compete on the quality and speed of graphics. The most important thing to remember is don’t write directly to the screen if you don’t have to. But if you do need to, an article that provides some guidelines is “Graphical Truffles: Writing Directly to the Screen,” develop, Issue 11.
Following are some additional articles that animation and game developers find useful:
• “Palette Manager Animation,” develop, Issue 5.
• “Using the Palette Manager Off-Screen,” develop, Issue 10.
• “QuickDraw’s CopyBits Procedure: Better Than Ever in System 7.0,” develop, Issue 6.
• “Graphical Truffles: Animation at a Glance,” develop, Issue 12.
Also, some sample code that can speed your development is given as SC.015.Offscreen and SC.016.OffSample (Dev CD Jan 93:Technical Documentation:Sample Code: Macintosh Sample Code).
Animation on the Macintosh does take some work. Nevertheless, we’ve seen some pretty amazing animations developed on the Macintosh.
Inside Macintosh Volume V PnPixPat & BkPixPat doc fix
Date written: 12/4/92
Last reviewed: 3/1/93
Inside Macintosh Volume V (page 103) says that when a PICT pattern opcode (for instance, 0x0012) comes along, and the pattern isn’t a dither pattern, the full pixMap data follows the old-style 8-byte pattern. The full pixMap data structure described on page 104 indicates that a pixMap starts with an unused long (baseAddr placeholder), followed by the rowBytes, bounds, and so on. However, looking at the Pict.r file on the October 1992 Developer CD, at the same opcode (BkPixPat == 0x0012), the first data field after the old-style pattern (hex string[8]) is the rowBytes field (broken down into three bitstrings). The baseAddr placeholder field isn’t there. Which is correct?
___
The Inside Macintosh documentation on pages V-103 and V-104 is wrong. The Pict.r file correctly describes the format of the PnPixPat and BkPixPat opcodes. So there shouldn’t be a baseAddr field in the pixMap record of a pattern as stored in the PnPixPat of a PICT. However, the baseAddr does occur in a 'ppat' resource as described on page V-79. Thanks for pointing out this discrepancy.
Disabling Macintosh Color QuickDraw for testing
Date written: 9/14/92
Last reviewed: 6/14/93
Is there an easy way to disable Color QuickDraw on a Macintosh? I want to do this for testing our application, to make sure it works correctly on a machine without Color QuickDraw.
___
There’s no easy, or perhaps even hard way to disable features built into the system software your particular machine requires. It’s designed to work well, not to be toggle-able.
Even the hard way isn’t a sure thing—trying to patch out all the Color QuickDraw traps could confuse the rest of the system software, which internally may use undocumented routines to accomplish its tasks.
The easiest way to test on non-Color QuickDraw machines is to get one. Fortunately, the machines without Color QD are the lowest end of the Macintosh price spectrum—such as the Macintosh Classic, PowerBook 100, and Macintosh SE. You can probably rent or borrow one of these if the prices don’t fit your current budget.
Using a Macintosh PICT file that’s larger than available memory
Date Written: 6/18/90
Last reviewed: 6/14/93
How can I read a 2 MB PICT file into only 1 MB of memory?
___
You can’t read it in since you don’t have enough memory, but drawing the picture contained in the file using a technique called “spooling” increases your chances of using a 2 MB PICT file with 1 MB memory. Spooling is documented in the Color QuickDraw chapter of Inside Macintosh Volume V (pages 88–89).
Getting a single scan line from a PICT file
Date Written: 6/18/90
Last reviewed: 6/14/93
Is there any way to obtain a particular scan line from a PICT file?
___
A PICT file may contain more than just pixmaps, so getting one scan line out of it is not possible. The file may also contain other elements that overlap, such as rects and arcs. The only way to obtain a single line is to draw it off-screen and then, once the whole image is in memory, you can go and study individual pixels.
Determining pixel depth from PICT files
Date Written: 6/20/90
Last reviewed: 9/17/91
How do you find out the pixel size of a PICT file on the disk?
___
A picture is by nature independent of depth. For example, you can have a picture containing DrawRects and LineTos and therefore lacking any info regarding depth.
On the other hand, if the picture you are looking at has pixmap opcodes in it, then each pixmap contains its own pixel size and in this case a picture can have a number of depths associated with it.
If you want to see the pixel size for each pixmap opcode in a picture, replace all the bottleneck routines and every time the bitsProc is called you can see the pixmap and get the info out. Since the picture is in a file, you can use the spooling technique described in the QuickDraw chapter in Inside Macintosh Volume V. Be ready to deal with multiple, possibly different, pixmaps as well as direct pixmaps if the picture was created under 32-bit QuickDraw.
”KnowsPICT,” on the Developer CD Series disc, extracts this kind of information. The System 7.0 Picture Utilities package gets this information too.
BitMapToRgn for non-Color QuickDraw Macintosh models
Date Written: 11/9/90
Last reviewed: 6/14/93
Is _BitmapToRegion available on any pre-System 7 non-Color QuickDraw configurations such as the Macintosh Classic, Plus, or SE? If not, is source or a library module available so that I don’t have to take the time and compatibility risk of rolling my own?
___
BitMapToRegion works on pre-color Macintosh systems. You can license BitMapToRegion from
Software Licensing
Apple Computer, Inc.
20525 Mariani Ave. MS:38-I
Cupertino, CA 95014
AppleLink: SW.LICENSE
Phone:(408) 974-4667
Macintosh QuickDraw pixel map stack requirements
Date Written: 12/3/90
Last reviewed: 5/21/91
What are the guidelines for determining how much of an image CopyBits can copy to a Macintosh pixel map at one time, given a particular set of characteristics for the source map and the destination map and given how much stack space is available? For example, say that we have an 8-bit-deep pixmap to be copied to a 32-bit-deep pixMap using the ditherCopy mode and expanded by a factor of 4, and we have 45K of stack space.
___
CopyBits’ stack requirement depends on the width of each scan line (rowBytes). The rule of thumb is that you need at least as much stack as the rowBytes value in your image (which can be huge with 32-Bit QuickDraw), with the following additional modifiers: Add an additional rowBytes for dithering; add an additional rowBytes for any stretching (source rect != dest rect); add an additional rowBytes for any color map changing; add an additional rowBytes for any color aliasing. The stack space you need is roughly five times the rowBytes of your image. In general, you’re better off processing narrower scan lines. Reducing the vertical size will not affect stack requirements. Narrow, tall bands (if you can use them) will reduce the stack requirements.
Color and non-Color QuickDraw trap dispatch differences
Date Written: 1/28/91
Last reviewed: 6/14/93
Why does a call to RGBForeColor cause a corruption of the stack without resulting in an unimplemented trap error on non-Color QuickDraw Macintosh systems?
___
The trap dispatcher on Color QuickDraw and non-Color QuickDraw machines are different. If you look at page 89 of Inside Macintosh Volume I, you’ll see the toolbox trap word format as it was in the days before Color QuickDraw. Bit 9 was “reserved for future use” and was ignored by the trap dispatcher, and so it was normally set to 0. That means that valid toolbox traps could either look like $A8XX or $A9XX as long as the auto-pop bit was turned off. Color QuickDraw machines have a trap dispatcher that uses that reserved bit to allow for more trap words, and therefore it has a much larger trap dispatch table. Color QuickDraw traps have that reserved bit set, so those traps look like $AAXX or $ABXX.
When a non-Color QuickDraw machine tests to see if a trap is implemented or not, it just checks the trap dispatch table to see if a routine is implemented for that trap or not. Because the reserved bit is ignored, trap words that look like $AAXX are treated as equivalent to $A8XX and trap words that look like $ABXX are treated as equivalent to $A9XX. The trap word for RGBForeColor is $AA14. If you call RGBForeColor on a non-Color QuickDraw machine, $AA14 is treated as $A814, which is the trap word for SetFractEnable. SetFractEnable is implemented on 128K ROM machines or greater, so no unimplemented trap error occurs.
If you look at recent DTS sample programs, such as the Utilities sample (SC.025.Utilities, which you can find on AppleLink in Developer Support and on the current developer CD), you’ll see a routine in Utilities.c called TrapExists. It takes into account the size of the trap dispatch table so that you can tell in one call whether a routine is implemented or not regardless of whether it’s a Color QuickDraw trap or not and regardless of what kind of Macintosh you’re running on.
Under system software version 7.0, the trap dispatcher is modified on non-Color QuickDraw machines so that many Color QuickDraw traps are implemented and work as well as they can in black and white.
Macintosh OpenCPicture 72-dpi calculation bug
Date Written: 2/12/91
Last reviewed: 6/14/93
The 32-Bit QuickDraw _OpenCPicture call incorrectly calculates the 72-dpi frame width if the height of the native resolution srcRect exceeds 910 dots. To work around this problem, I calculate the 72-dpi frame independently, and store it in the PicHandle returned by _OpenCPicture.
___
It’s a known bug that under Macintosh system software versions 6.0.5 and 6.0.7 with 32-Bit QuickDraw 1.2, OpenCPicture doesn’t properly calculate the right coordinate of the 72-dpi picFrame if the height of the srcRect (native resolution rectangle) multiplied by 72 exceeds $0000FFFF. That works out to a maximum height of 910 pixels, just as you found. This bug is fixed in System 7.0, but gestaltQuickdrawVersion returns $0220 both under system software versions 6.0.5 and 7.0, so you can’t tell whether the bug is fixed that way. Instead, you should use Gestalt with the gestaltSystemVersion selector. If the returned value is $0700 or greater, then let OpenCPicture handle the picFrame calculation; otherwise you should do the calculation yourself.
GetGWorldPixMap bug and workaround
Date Written: 3/12/91
Last reviewed: 6/14/93
Why does GetGWorldPixMap (when called on a Macintosh II, IIcx, or IIx running system software version 6.0.5 or 6.0.7 with 32-Bit QuickDraw 1.2) return a combination of the device field (two bytes) and the first two bytes of the portPixMap field? Is this a bug?
___
Your analysis of GetGWorldPixMap is exactly right: It doesn’t work correctly in system software version 6.0.5 and 6.0.7 with 32-Bit QuickDraw 1.2. It returns a value that’s two bytes before the value it’s supposed to return.
The solution is to use GWorldPtr->portPixMap instead of GetGWorldPixMap. It’s safe to do this, but you should use GetGWorldPixMap under System 7. Not only is the bug fixed there, but dereferencing the port is dangerous under System 7 because it may not be CGrafPort. Use Gestalt with the gestaltQuickdrawVersion selector to determine whether you can use GetGWorldPixMap. If Gestalt returns a value from gestalt8BitQD ($0100) through gestalt32BitQD12 ($0220), then GetGWorldPixMap either doesn’t exist or is the buggy version. If it returns gestalt32BitQD13 ($0230) or higher, then GetGWorldPixMap does exist and works correctly. Interestingly, GetGWorldPixMap can be called on a black-and-white QuickDraw machine under System 7. It returns a handle to a structure which should be treated as a BitMap structure, though there are some undocumented fields after the normal BitMap fields. To tell whether GetGWorldPixMap is available on a black-and-white QuickDraw machine, you must check the system software version by calling Gestalt with the gestaltSystemVersion selector. If it returns $0700 or higher, GetGWorldPixMap is available.
System 7 TextMode problem and workaround
Date Written: 6/12/91
Last reviewed: 8/13/91
Our application uses the TextMode (blend + mask) as documented in Inside Macintosh Volume V (blend is equal to the current ditherCopy constant) to make translucent text. Under System 7, this transfer mode causes garbage to appear when the text is drawn. Is there a way to work around the problem? Will there be a fix?
___
The problem you are seeing is due to the use of CopyDeepMask instead of the old-fashioned CopyBits to do the job. It is being studied now, and the hope is that it will work as advertised in a future release. One workaround is to render the text to an off-screen pixmap and then call CopyBits (using blendMode) to actually put it in the picture.
Using dithering and animation on the same Macintosh image
Date Written: 6/19/91
Last reviewed: 6/14/93
When setting up a dithered grayscale image for subsequent animation (to adjust brightness, for example), a conflict arises between the use of Palette animation and the ditherCopy CopyBits mode. This problem is demonstrated in the develop #5 GiMeDaPalette code sample: If you change srcCopy to ditherCopy in the CopyBits call, then run the program and select Animate, the resulting image is pure black and white, with what appears to be an attempt to dither with just the black-and-white color table entries (that are not reserved for animation).
This happens because ditherCopy tries to use the inverse table to do color matching, but when the image is animated, the inverse table colors are limited to just black and white.
To work around the problem, you can jump into the bottlenecks and when you see the PICT hitting the opcode for CopyBits, change the mode adding the ditherCopy constant. This way the dithering happens when you do the call to DrawPicture and not later on. This makes it possible to use dithering and animation on the same image.
Rendering color PICTs in a black-and-white environment
Date Written: 7/22/91
Last reviewed: 9/17/91
I want to be able to render a color PICT as a black-and-white image substituting patterns for colors. My images are pretty small and have fewer than 16 colors. What do you suggest as the easiest way?
___
One easy way is to take advantage of 32-Bit QuickDraw and System 7.0’s ditherCopy transfer mode modifier or flag (documented in Inside Macintosh Volume VI, page 17-17). Call DrawPicture into an off-screen pixmap with the pixel depth of the original color PICT. Then call CopyBits to copy the pixmap to the screen, with srcCopy + ditherCopy as the transfer mode. This will result in a nicely dithered image on the black-and-white end.
Under System 6 without 32-Bit QuickDraw, the solution is not nearly so cut and dried. One way might be to take advantage of the fact that DrawPicture goes through the QuickDraw bottlenecks for drawing. For each grafproc in your PICT, you’d intercept StdBits during DrawPicture and call your own dithering routine to examine the foreground color and set the pen pattern or fill pattern so that it has about the same lightness as the original color.
Well, this came out as a great sales pitch for writing a System 7-savvy app!
Highlighting ignored if foreground same as background color
Date Written: 8/7/91
Last reviewed: 6/14/93
Under System 7, but not System 6, HiliteMode doesn’t work when the foreground and background colors are similar. Is this a bug?
___
Yes, it’s a bug. The problem you encounter exists whenever the background and foreground color map to the same color table index. If the foreground color is the same as the background color, highlighting is ignored. Therefore, you should always make sure the foreground and background colors are different when using HiliteMode.
Gestalt 'qdrw' selector bug and workaround
Date Written: 8/1/91
Last reviewed: 6/14/93
Why does Gestalt tell me I have Color QuickDraw features on a non-Color QuickDraw machine?
___
The gestaltQuickdrawFeatures ('qdrw') selector, used for determining your system’s Color QuickDraw features, has a bug that causes it to tell you incorrectly that noncolor machines have color. The fix is quite simple: Gestalt has another selector, gestaltQuickdrawVersion ('qd '), which simply returns the QuickDraw version number. This version number is < gestalt8BitQD for classic QuickDraw and >= gestalt8BitQD for Color QuickDraw (see Inside Macintosh Volume VI, page 3-39, for more information). The trick is to ask Gestalt for the QuickDraw version first; once you’ve determined that you have Color QuickDraw, the 'qdrw' selector is OK to use to find out specifics.
GetPixelsState is slow sometimes
Date Written: 8/27/91
Last reviewed: 6/14/93
Why do I sometimes see incredible slowdowns under System 7.0 when calling either GetPixelsState or LockPixels (I’m not sure which) for the PixMapHandle of a GWorld allocated in temporary memory?
___
GetPixelsState takes an arbitrary amount of time since it makes a call to RecoverHandle to get the handle pointing to the baseaddr. Therefore, the slowdown you see as actually due to the call to RecoverHandle, which is slow because it must traverse the heap to find the pointer to the baseaddr. LockPixels is not responsible for the slowdown because it does not make call to any traps that could take an extended amount of time.
OpenCPicture and PICTs other than 72 dpi
Date Written: 10/2/91
Last reviewed: 6/14/93
Can I use OpenCPicture to create PICTs with a higher resolution than 72 dots per inch (dpi)?
__
There’s good news and bad news: The good news is that you’re on top of the situation, which means the bad news is that there aren’t better ways to do what you want to do, mostly. Here’s the scoop:
You can use vRes and hRes in pictures opened with OpenCPicture to tell QuickDraw it’s not a 72-dpi picture, and as long as the application that receives the picture uses DrawPicture to image it, QuickDraw will Do The Right Thing—scaling it on the screen to 72 dpi instead of making it humongously large. Unfortunately, this way you lose hairlines; if you print such a picture to a 72-dpi grafPort (like the LaserWriter driver normally returns), you’ll get 1/72-inch lines instead of 1/300-inch lines as you probably want.
(This can work correctly, but the receiving application has to notice that your picture is bigger than 72 dpi and ask PrGeneral to increase the resolution of the printing grafPort accordingly, and this doesn’t always or often happen.)
No System 7 QuickDraw alpha channel support
Date Written: 10/23/91
Last reviewed: 6/14/93
How can I directly access the alpha channel (the unused 8 bits in a 32-bit direct pixel using QuickDraw) under System 7? Under System 6 it was easy, but under System 7’s CopyBits the alpha channel works with srcXor but not with srcCopy.
___
With the System 7 QuickDraw rewrite, all “accidental” support for the unused byte was removed, because QuickDraw isn’t supposed to operate on the unused byte of each pixel. QuickDraw has never officially supported use of the extra byte for such purposes as an alpha channel. As stated in Inside Macintosh Volume VI, page 17-5, “8 bits in the pixel are not part of any component. These bits are unused: Color QuickDraw sets them to 0 in any image it creates. If presented with a 32-bit image—for example, in the CopyBits procedure—it passes whatever bits are there.”
Therefore, you cannot rely on any QuickDraw procedure to preserve the contents of the unused byte, which in your case is the alpha channel. In fact, even CopyBits may alter the byte, if stretching or dithering is involved in the CopyBits, by setting it to 0. Your alternatives are not to use the unused byte for alpha channel storage since the integrity of the data cannot be guaranteed, or not to use QuickDraw drawing routines that can alter the unused byte.
BitsToRgn and MPW BitMapToRegionGlue
Date Written: 10/29/91
Last reviewed: 6/14/93
Which version of the system software first contained the call BitsToRgn? Is there a workaround for this call if my users have an earlier version of system software?
___
The call BitmapToRegion was introduced with 32-Bit QuickDraw and became fully documented in Volume VI of Inside Macintosh, which is primarily System 7 information. However, since the differences between System 7’s QuickDraw and 32-Bit QuickDraw are minor, most of System 7’s QuickDraw routines are available in system software prior to System 7.0 using the 32-bit QuickDraw INIT.
To check to see if a system contains 32-bit QuickDraw, you can use the following snippet of code:
/* Find out if GWorlds and CQD are implemented on this machine */
If you are using MPW as a development platform, MPW has a library call you can use that will allow you to use the routine regardless of whether or not 32-bit QuickDraw exists. The glue routine is called BitMapToRegionGlue() and is available to MPW users. Substitute this call for BitMapToRegion calls and the glue code will take care of patching in the proper code if 32-bit QuickDraw does not exist. If you’re using Think C, you can use the oConv utility to convert the MPW object file into a Think C usable format.
Ensuring even rowBytes for 'cicn' resources
Date Written: 12/4/91
Last reviewed: 6/14/93
Is there any way to force bitmaps and masks within a 'cicn' resource to have an even rowBytes (using ResEdit)? I want to avoid duplicating icon bitmaps—one for color systems set to B&W and one for B&W systems—to reduce program size as well as development and maintenance costs. The bitmaps in the 'cicn' can also be sized specifically to the task, whereas the old B&W icons are of a fixed size and contain no sizing information. It’s simple enough to read in a 'cicn' and extract the bitmap. The problem is that on a 68000 (no Color QuickDraw), if rowBytes is odd, an odd address trap results.
___
There isn’t any way to get ResEdit itself to create bitmaps with even rowBytes for 8 x 8 'cicn' resources, but here are few suggestions:
You could process your 'cicn' resources first, so that they have bitmaps as you require them. To alter the resource with a quick little program would be trivial, especially given that the bitmap data sits last in the 'cicn'. All you’d need to do is expand the bitmap image data by padding each line to an even length and then changing the rowBytes value. Or you could de-rez the 'cicn's and patch them with a text editor, either by hand or with a search-and-replace script of some kind.
I have two gray-colored pixmaps that I wish to blend together; one is on the screen, the other in an off-screen pixmap. I use CopyBits to copy the off-screen to the screen, but it does not seem to blend them. Instead, it seems to match the colors of the screen bitmap to the closest colors in some table, thus having the effect of reducing the number of colors displayed on the screen bitmap. Any suggestions?
___
There are two distinct questions here: 1) Why ain’t it blending? and 2) What’s this banding for? The first problem is almost certainly because OpColor isn’t set properly. This is a third, implicit, operand on several arithmetic graphics operations, including blend. For blend, it describes the proportions to mix the source and destination colors in the blend. For an equal mix, you should set this color to a halfway gray. (Call OpColor() with a color where red, green, and blue all equal $8000.) This effect is described in the description of the blend mode on page 60 of Inside Macintosh Volume V. Unfortunately, the initial value for OpColor is black (0,0,0), so you were seeing no mixing of your off-screen data.
The second half of your question is why you’re getting a banding effect. (When you fix the above problem, you’ll still get banding.) Unfortunately, the arithmetic modes are constrained by the size of the inverse table. As your screen no doubt uses the default 4-bit inverse table, you’ll find that you’ll get only 2^4 = 16 levels of gray. If you enlarge your screen’s inverse table to 5 bits, the maximum allowable, you’ll still only get 32 gray levels. (To do this, set the gdResPref field in the GDevice to 5, then call MakeITable().) The only way to get a fully-gradual, great-looking effect is to do all the work off-screen in 24-bit deep pixmaps, and then copy it to the screen. Because they can operate directly on colors, rather than having to work through the intermediary of color indices, direct pixmaps are not limited by inverse tables (in fact, they don’t even have real inverse tables). You could use 16-bit pixmaps, but they only provide 32 grays (having only 5 bits for each component), so this wouldn’t be any better than increasing the size of the inverse table.
Icon dimming under System 7 and System 6
Date Written: 1/6/92
Last reviewed: 6/14/93
When you bring up the Finder windows under System 7 on a color system and click a control panel item icon, it paints itself that fancy gray. How can I get that effect?
___
To get the fancy System 7 icon dimming to work in your program, read the Macintosh Technical Note “Drawing Icons the System 7 Way,” and use the icon-drawing routines contained in it. The routines show how to use the Icon Toolkit, which is what the Finder uses. If you want the same effect under System 6, you’ll have to emulate the dimming of the icons via QuickDraw; the IconDimming sample code in the Snippets folder on the Developer CD Series disc shows how to do this.
QuickDraw out of memory if debugger invoked by “Jackson”
Date Written: 3/11/92
Last reviewed: 6/14/93
I am getting a strange bug in which the Macintosh debugger is being invoked by an A-trap marked “Jackson” when I call SetCCursor in certain situations and a second monitor is hooked up. The cursor structure being passed appears to be valid. I’ve also been crashing unexpectedly in this same spot for the past few weeks. I assume Jackson is some kind of error assertion that was left in System 7’s Color QuickDraw code. What gives?
___
Jackson was a code name for 32-Bit QuickDraw. The trap you refer to is in fact never called; it’s not supposed to be encountered by you ever. The trap is reserved for Apple to use in future versions of Color QuickDraw. If you examine the code directly preceding the _Debugger, you will notice that it is doing
MOVEQ #$19,D0
JSR ([$1524])
which for you and me is
MoveQ #25,D0 ; say that memory is full…
_SysError ; and call syserror
the line following would be...
_Debugger ; Hey! sysError came back! Better drop into the debugger
What’s all this tell you? You have a debugger installed that is rts’ing from the SysError vector (you aren’t supposed to return from SysError normally), or you have installed your own SysError vector which is rts’ing. At any rate, if you examine the code directly following the debugger statement and see what it does, you might imagine the source code looks something like this:
MemFull MoveQ #25,D0 ; say that memory is full...
_SysError ; and call syserror
; If it returns better go into the debugger since its not supposed to return
_Debugger ; Hey! sysError came back!
;
CallNewHand _NewHandle
bne.S MemFull ; could not get the memory, just die
rts
What’s happening is that you’re running out of memory somehow (several places call MemFull, not just the above place), so you’d need to use a stack crawl to figure out how you got there. But, the bottom line, QuickDraw has run out of memory and cannot continue; it tried to put up a system error dialog to tell the user and for some reason the machine did not get restarted and the SysError vector returned. You are now in your debugger, since QuickDraw put up the system error dialog because it could not continue.
ditherCopy not supported on LaserWriter or ImageWriter
Date Written: 5/31/91
Last reviewed: 11/6/91
ditherCopy is not supported on LaserWriters or ImageWriters. On a LaserWriter, ditherCopy gets misinterpreted and inverts the image. On an ImageWriter it’s treated as a srcCopy. The ImageWriter driver doesn’t support color grafPorts, which is the only way to do the pixel image required for ditherCopy. Use srcCopy instead for both printers.
Macintosh Color QuickDraw CalcCMask and SeedCFill clarified
Date Written: 1/1/90
Last reviewed: 11/21/90
I’m having trouble using CalcCMask and SeedCFill. What am I doing wrong?
___
There is some confusion regarding the use of the Macintosh Color QuickDraw routines CalcCMask and SeedCFill, which are analogous to the older CalcMask and SeedFill. Much of the confusion was caused by early documentation errors. Be sure you have the release version of Volume 5 of Inside Macintosh and version 2.0 or later of the MPW interface files.
The correct interface for CalcCMask is:
PROCEDURE CalcCMask(srcBits, dstBits: BitMap;
srcRect, dstRect: Rect;
seedRGB: RGBColor;
matchProc: ProcPtr;
matchData: LongInt);
The correct interface for SeedCFill is:
PROCEDURE SeedCFill(srcBits, dstBits: BitMap;
srcRect, dstRect: Rect;
seedH, seedV: INTEGER;
matchProc: Ptr;
matchData: LongInt);
Each routine calculates a one-bit deep bitmap representing either the mask or the fill area depending upon the routine. In both cases, the source bitmap may be either a bitmap or a pixmap, but the destination must be a bitmap, because it must have a depth of one-bit.
It is difficult to pass a pixmap for the source parameter because of Pascal’s type checking. To get around this difficulty, you can declare a new type:
BitMapPtr = ^BitMap
then use it to coerce the pixmap as follows:
SeedCFill(BitMapPtr(@myPixMap)^, ...);
If you have a PixMapHandle, do the following:
SeedCFill(BitMapPtr(myPixMapHandle^)^, ...);
If you are using a grafPort (or a window), you can pass myWindow^.portBits and not have to worry about whether the port uses a bitmap or a pixmap.
Most of the other parameters are explained in detail in Inside Macintosh. To use the matchProc and the matchData parameters, though, you need more information.
As stated in Inside Macintosh, the matchProc parameter is a pointer to a routine that you would like to use as a custom SearchProc. To better understand how this is used, it is helpful to know how SeedCFill and CalcCMask actually work.
Both routines start by creating a temporary bitmap which, by definition, is one bit deep. The source pixmap (or bitmap) is then copied to the temporary bitmap using CopyBits. This copy causes the image to be converted to a depth of one-bit. Now with a normal black-and-white image, the standard CalcMask or SeedFill routine is used to generate the destination bitmap.
Most of the real work is done in the original call to CopyBits, which maps the pixmap image to a monochrome bitmap equivalent. For each color in the source pixmap, CopyBits will map it to either black or white. Which colors map to black and which ones to white is determined by the SearchProc.
SeedCFill installs a default SearchProc that maps all colors to black except for the color of the pixel at (seedH,seedV). SeedFill then calculates as usual the fill mask for the white bits .
The default SearchProc for CalcCMask maps all colors to white except the color passed in the seedRGB parameter. The seedRGB parameter, then, would be the color of the item that you wanted to “lasso.”
But suppose you want to fill over all colors that were shades of green, not just the particular shade of green at (seedH,seedV). Or maybe you want to fill over all colors that are lighter than 50 percent brightness. Or maybe you want to use dark colors as edge colors for CalcCMask. To do such things, you need to pass a pointer to your own SearchProc in the matchProc parameter.
Because your matchProc is just a custom search procedure for the Color Manager, it should be declared as one, but Volumes I–V of Inside Macintosh have documented this routine incorrectly. The correct declaration for a custom SearchProc is as follows:
FUNCTION SearchProc(VAR RGB: RGBColor;
VAR result: LongInt) : Boolean;
Normally, as each SearchProc is installed, it is added to the head of the SearchProc chain, so that it is called before all of the other ones that were already installed. When a SearchProc is installed, it can do one of three things:
1. Completely ignore the call by returning FALSE and not modifying any of the input parameters;
2. Completely handle the call by setting the result parameter to be the index into the color table that matches (according to your rules) the RGB parameter. In that case, the SearchProc returns TRUE;
3. Partially handle the call by modifying the RGB parameter, then returning FALSE.
In cases 1 and 3, the Color Manager continues down the SearchProc chain until it finds one that returns TRUE. If none of the custom routines handle the call, then the built-in default routine is used. In case 3, you can change the RGB color that is being matched. For example, if you want all shades of green to map to pure green, modify the RGB color, then return FALSE, letting the Color Manager find the index of that green in the color table.
In case 2, you return TRUE to indicate that you handled the call, and you return the color table index in the result parameter. The Color Manager then uses that index. For example, if you want to substitute white for all colors that can’t be matched exactly in the color table, then each time you get called you either return the index into the color table of the exact color, or 0 (which is the index for white) for all other colors.
A custom SearchProc for SeedCFill and CalcCMask should always return TRUE because the default Color Manager SearchProc usually doesn’t make sense. Because SeedCFill and CalcCMask are using CopyBits to copy to a 1-bit bitmap, you need to set the result to be either 0 or 1 (the only possible values in a 1-bit bitmap). A result of 0 is white, and a result of 1 is black.
All colors for SeedCFill that should be “filled over” would generate a result of 0 (white), and all colors that stop the fill generate a 1 (black). SeedFill is then called to fill the white area. All colors for CalcCMask that you want to form boundaries should generate results of 1 (black).
When your SearchProc gets called, the gdRefCon field of the current GDevice (theGDevice^^.gdRefCon) contains a pointer to the following record:
matchRec = RECORD
red: Integer;
green: Integer;
blue: Integer;
matchData: LongInt;
END;
The red, green, and blue parameters for SeedCFill are the values of the color of the pixel at (seedH,seedV). For CalcCMask, they are the fields from the seedRGB parameter. Your SearchProc can use this information to decide which colors are “fill-over” colors and which colors are “boundary” colors. For example, if you always set (seedH,seedV) to be the mouse point, your SearchProc then bases its decisions using the color of the pixel under the cursor. For example, the user clicks a shade of green, so all shades of green get filled over.
The matchData field contains the value that you passed into the SeedCFill or CalcCMask routines in the matchData parameter. The use of this field is completely user-defined. For example, since your SearchProc routine may be a separate module, you might want to use this field to pass a handle to your variables. This field can contain a handle, a pointer, a long integer, or whatever; or you can just ignore this field altogether.
Warning: There are some features of CalcCMask and SeedCFill you should be aware of. To understand them, you should be familiar with the use of CalcMask and SeedFill, which are described in the QuickDraw chapter of Inside Macintosh Volume IV.
CalcCMask and SeedCFill both use a parameter set that is very similar to the one used by CopyBits. CalcMask and SeedFill, however, are a different story. Instead of passing bitmaps and rectangles to SeedFill and CalcMask, these routines use an unusual set of parameters that describe the memory to be operated upon in terms of pointers, height, width, and offsets to the next row (rowBytes). Although these parameters are fairly easy to calculate, there are some limitations.
The most restrictive limitation is that the width of the rectangle used must be an even multiple of 16 bits. This limitation exists because the width of the rectangle is passed to SeedFill and CalcMask as a number of words (2 bytes). When calculating this parameter, SeedCFill and CalcCMask round down to an even word boundary. This rounding means that the rectangles you pass to CalcCMask and SeedCFill should be an even multiple of 16 pixels in width. If they are not, then the rightmost portion of the mask will be garbage.
To figure out the color of the pixel at (seedH,seedV), SeedCFill calls GetCPixel. GetCPixel finds the color of the pixel at (h,v) in the current port. Therefore, if you pass a pixmap that is not the pixmap of the current port you will get bizarre results. In other words, seedH and seedV are expressed in the local coordinates of the current port, not the coordinate of the source pixmap.
You have two methods to make it work. First, always pass the pixmap of the current port as the source parameter. If you are using an off-screen pixmap, it is a good idea to have an associated port for it, and then call SetPort, passing it a pointer your off-screen port, before you call SeedCFill.
The second method involves letting SeedCFill get some wrong value for the color at (seedH,seedV) then using your own custom SearchProc to do the real work. The default SearchProc for SeedCFill relies on getting the correct color, but your SearchProc doesn’t have to.
SeedCFill also makes the assumption that the seedH and seedV parameters are in the local coordinate system of the destination bitmap. This assumption comes into play when SeedCFill calculates the seedH and seedV parameters for SeedFill.
All this means that SeedCFill only works correctly if the source pixmap, destination pixmap, and current port all use the same coordinate system. Because of the above problem, this is almost automatic since the current port’s portRect and the bounds of the source pixmap have to be the same anyway.
The easiest way to make all this work is to have your main port be an even multiple of 16 pixels wide. Then, make sure that your source and destination structures (pixmap or bitmap) are all the same size and all have origins of (0,0).
Macintosh PICT color picture file format
Date Written: 1/1/90
Last reviewed: 6/14/93
Is there a general file format for color pictures that is common to all of the color paint programs? If so, where is it documented?
___
Apple supports (and encourages developers to support) one file type for pictures: the PICT file type. Most paint-type programs handle PICT files.
A PICT file is composed of two parts in its data fork; the first 512 bytes are for the file header, which contains application-dependent information. You have to contact the individual publishers to find out their particular data structures. For example, you can contact Claris Technical Support at AppleLink CLARIS.TECH or (415) 962-0371 for the file header MacDraw writes to its files.
The rest of the data in the file is picture data as created by Macintosh QuickDraw with OpenPicture. You can find the information about this data in Volume V of Inside Macintosh (pages 84–105); this section also shows how to read/write PICT files.
You can also check the Macintosh Tech Note “Displaying Large PICT Files” for more details on the subject.
X-Refs:
DTS Macintosh Technical Note “QuickDraw’s Internal Picture Definition”
DTS Macintosh Technical Note “Displaying Large PICT Files”
Mac pixmap is clipped to visRgn defined by screenBits.bounds
Date Written: 1/1/90
Last reviewed: 11/21/90
I’m drawing into a large off-screen bitmap (pixmap), but anything drawn outside the 640- by 480-pixel Macintosh screen area doesn’t get written to the pixmap. Why not?
___
When you create a new port with OpenPort or OpenCPort the visRgn is initialized to the rectangular region defined by screenBits.bounds (IM I:163). If your port has a large portRect, any drawing will be clipped to the visRgn and you will lose any drawing outside of the screenBits.bounds rectangle.
To correct this set the visRgn of the port to coincide with your port’s portRect after creating the port.
Also note that OpenPort initializes the clipRgn to a wide-open rectangular region (-32768, -32768, 32767, 32767). Some operations, like OpenPicture, can fail with this setup, so try setting clipRgn to a smaller rectangle.
X-Refs:
DTS Macintosh Technical Note “Pictures and Clip Regions”
DTS Macintosh Technical Note “Drawing into an Off-Screen Pixel Map”
Using Macintosh System 7 OpenCPicture for higher resolution
Date Written: 1/1/90
Last reviewed: 6/14/93
We want to use OpenCPicture for higher resolution, not for color per se. Can OpenCPicture in System 7 be used with non-Color as well as Color QuickDraw Macintosh computers?
___
Yes, with System 7, OpenCPicture can be used to create extended PICT2 files from all Macintosh computers. Under System 6.0.7 or later, you must test for 32-Bit QuickDraw before using OpenCPicture. You can do this by calling Gestalt with the gestaltQuickdrawVersion selector. If it returns gestalt32BitQD or greater, then 32-Bit QuickDraw is installed.
How to identify 32-Bit QuickDraw version
Date Written: 1/1/90
Last reviewed: 6/14/93
How can my program find out which version of Macintosh 32-Bit QuickDraw is running?
___
The following code snippet demonstrates how to use the Gestalt Manager to determine which version of 32-Bit QuickDraw is installed. There is no way to determine the version of 32-Bit QuickDraw before Gestalt. For 32-Bit QuickDraw version 1.2, Gestalt returns 2.2. Inside Macintosh Volume VI describes the Gestalt Manager in detail.
#defineTRUE0xFF
#defineFALSE0
#define Gestalttest0xA1AD
#define NoTrap0xA89F
main()
{
OSErrerr;
longfeature;
if ((GetTrapAddress(Gestalttest) != GetTrapAddress(NoTrap))) {
err = Gestalt(gestaltQuickdrawVersion, &feature);
if (!err) {
if ((feature & 0x0f00) == 0x0000)
printf ("We have Original QuickDraw version 0.%x\n", (feature & 0x00ff));
else if ((feature & 0x0f00) == 0x0100)
printf ("We have 8 Bit QuickDraw version 1.%x\n", (feature & 0x00ff));
else if ((feature & 0x0f00) == 0x0200)
printf ("We have 32 Bit QuickDraw version 2.%x\n", (feature & 0x00ff));
else
printf ("We don't have QD\n");
}
else
printf ("Gestalt err = %i\n",err);
}
else
printf ("No Gestalt\n");
}
Macintosh QDError function under System 6 and System 7
Date Written: 1/1/90
Last reviewed: 12/7/90
Under what System 7 and System 6 conditions is it legal to call the Macintosh QDError function?
___
Under System 7, QDError can be called from all Macintosh computers. (System 7 supports RGBForeColor, RGBBackColor, GetForeColor, and GetBackColor for all Macintosh computers as well.) On a non-Color QuickDraw Macintosh, QDError always returns a “no error.” Under System 6, QDError cannot be used for non-Color QuickDraw Macintosh systems.
Macintosh CopyBits transfer modes changed for System 7
Date Written: 1/1/90
Last reviewed: 6/14/93
Why do some Macintosh CopyBits transfer modes produce different results for System 7 than for System 6?
___
Under System 6, the srcOr, srcXor, srcBic, notSrcCopy, notSrcOr, notSrcXor, and notSrcBic transfer modes do not produce the same effect for a 16- or 32-bit (direct) pixel map as for an 8-bit or shallower (indexed) pixel map. With Color QuickDraw these classic transfer modes on direct pixel maps aren’t color-based; they’re pixel-value-based. Color QuickDraw performs logical operations corresponding to the transfer mode on the source and destination pixel values to get the resulting pixel value.
For example, say that a multicolored source is being copied onto a black-and-white destination using the srcOr transfer mode, and both the source and destination are 8 bits per pixel. Except in unusual cases, the pixel value for black on an indexed pixel map has all its bits set, so an 8-bit black pixel has a pixel value of $FF. Similarly, the pixel value for white has all its bits clear, so an 8-bit white pixel has a pixel value of $00. CopyBits takes each pixel value of the source and performs a logical OR with the corresponding pixel value of the destination. Using OR to combine any value with 0 results in the original value, so using OR to combine any pixel value with the pixel value for white results in the original pixel value. Using OR to combine any value with 1 results in 1, so using OR to combine any pixel value with the pixel value for black results in the pixel value for black. The resulting image shows the original image in all areas where the destination image was white and shows black in all areas where the destination image was black.
Take the same example, but this time make the source and destination 32 bits per pixel. The direct-color pixel value for black is $00000000 and the direct-color pixel value for white is $00FFFFFF. CopyBits still performs a logical OR on the source and destination pixel values, but notice what happens in this case. Using OR to combine any source pixel value with the pixel value for white results in white, and using OR to combine any source pixel value with the pixel value for black results in the original color. The resulting image shows the original image in all areas where the destination image was black and shows white in all areas where the destination image was white—roughly the opposite of what you see on an indexed pixel map.
The newer transfer modes addOver, addPin, subOver, subPin, adMax, and adMin work consistently at all pixel depths, and often, though not always, correspond to the theoretical effect of the old transfer modes. For example, the adMin mode works similarly to the srcOr mode on both direct and indexed pixel maps. Also, 1-bit deep source pixel maps work consistently and predictably regardless of the pixel depth of the destination even with the old transfer modes.
Under system software version 7.0, the old transfer modes now perform by calculating with colors rather than pixel values. You’ll find that transfer modes like srcOr and srcBic work much more consistently even on direct pixel maps.
Which QuickDraw versions support SetEntries
Date Written: 3/3/92
Last reviewed: 6/14/93
I’m calling SetEntries to update the on-screen CLUT. Who implements this call? Does 32-Bit QuickDraw? In other words, does the 32-Bit QuickDraw INIT need to be around for this to work? What about monochrome machines?
I’m creating off-screen buffers by hand instead of using GWorlds. Is this the proper way of doing off-screen buffering when we don’t want to require the user to have 32-Bit QuickDraw?
___
SetEntries is part of the Color Manager, which exists with all Color QuickDraw versions. A good rule of thumb to follow is that if it is documented in Inside Macintosh Volume V, you don’t need 32-Bit QuickDraw to use it. Inside Macintosh Volume V documents standard Color QuickDraw. SetEntries does not work on monochrome Macintosh models, including the Classic II, SE, and PowerBooks.
Off-screen buffering: You should always use GWorlds if they exist; use Gestalt to test for them. This will assure that you can take advantage of the latest speed improvements. It is important to remember that under System 7 NewGWorld and accompanying calls are present in all Macintosh computers including black-and-white systems such as Classic and PowerBook 100 systems.
Macintosh pixel map maximum rowBytes change
Date Written: 4/22/91
Last reviewed: 6/14/93
The Color QuickDraw section of Inside Macintosh Volume VI states that the restriction on the rowBytes field in a pixmap has been relaxed from $2000 to $4000. When did this happen? Is it true for all 32-Bit QuickDraw versions? This affects our user configuration recommendations.
___
The maximum rowBytes extension to $3FFE or less applies only to 32-bit QuickDraw. Using pixmaps with rowBytes greater than $1FFE when 32-bit QuickDraw is not present is likely to cause problems such as garbage images or system crashes. Remember that 32-bit QuickDraw is always present under System 7.0 or higher.
Use assembly to flip a 24-bit off-port color pixmap
Date Written: 5/7/91
Last reviewed: 7/25/91
What’s the best approach to horizontally flip a 24-bit off-port color pixmap?
___
Unfortunately, you won’t be able to use CopyBits for this kind of procedure; you’ll have to write your own routine to move each pixel. I’d suggest doing this in assembly language to squeeze the best possible performance out of your code.
Why PlotCIcon requires GetCIcon instead of Get1Resource
Date Written: 4/26/91
Last reviewed: 6/17/91
Why do I have to use GetCIcon(resID) instead of Get1Resource('cicn',resID) forPlotCIcon to work correctly?
___
You apparently thought something that, at first, I thought also: that GetCIcon(resID) is just a utility routine that translates to Get1Resource('cicn',resID). However, this is not the case; GetCIcon not only gets the 'cicn' resource, but it also performs some minor surgery on the results, fills in some placeholder fields in the resource data, and the like. Basically, PlotCIcon can’t work without the things that GetCIcon does.
How Macintosh system draws small color icons
Date Written: 3/31/92
Last reviewed: 6/14/93
The code I added to my application’s MDEF to plot a small icon in color works except when I hold the cursor over an item with color. The color of the small icon is wrong because it’s just doing an InvertRect. When I drag over the Apple menu, the menu inverts behind the icon but the icon is untouched. Is this done by brute force, redrawing the small icon after every InvertRect?
___
The Macintosh system draws color icons, such as the Apple icon in the menu bar, every time the title has to be inverted. First InvertRect is called to invert the menu title, and then PlotIconID is called to draw the icon in its place. The advantage of using PlotIconID is that you don’t have to worry about the depth and size of the icon being used. The system picks the best match from the family whose ID is being passed, taking into consideration the target rectangle and the depth of the device(s) that will contain the icon’s image.
The Icon Utilities call PlotIconID is documented in the Macintosh Technical Note “Drawing Icons the System 7 Way”; see this Note for details on using the Icon Utilities calls.
Spooling and preserving Macintosh QuickDraw pixmap depth
Date Written: 2/11/92
Last reviewed: 6/14/93
When a picture that contains a pixmap is spooled into a window, how and when is the depth of the pixmap in the picture converted to the depth of the screens the window is on?
___
When a picture is spooled in, if QuickDraw encounters any bitmap opcode, it allocates a pixmap of the same depth as the data associated with the bitmap opcode, expands the data into the temporary pixmap, and then calls StdBits. StdBits is what triggers the depth and color conversions as demanded by the color environment (depth, color table, B&W settings) of the devices the target port may span (as when a window crosses two or more screens).
If there’s not enough memory in the application heap or in the temporary memory pool, QuickDraw bands the image down to one scan line and calls StdBits for each of these bands. Note that if you’re providing your own bitsProc, QuickDraw will call it instead of StdBits.
This process is the same when the picture is in memory, with the obvious exception that all the picture data is present; the color mapping occurs when StdBits does its stuff.
Determining the resolution of a PICT
Date Written: 6/10/92
Last reviewed: 6/14/93
In a version 2 picture, the picFrame is the rectangular bounding box of the picture, at 72 dpi. I would like to determine the bounding rectangle at the stored resolution or the resolution itself. Is there a way to do this without reading the raw data of the PICT resource itself?
___
With regular version 2 PICTs (or any pictures), figuring out the real resolution of the PICT is pretty tough. Applications use different techniques to save the information. But if you make a picture with OpenCPicture, the resolution information is stored in the headerOp data, and you can get at this by searching for the headerOp opcode in the picture data (it’s always the second opcode in the picture data, but you still have to search for it in case there are any zero opcodes before it). Or you can use the Picture Utilities Package to extract this information.
With older picture formats, the resolution and original bounds information is sometimes not as obvious or easily derived. In fact, in some applications, the PICT’s resolution and original bounds aren’t stored in the header, but rather in the pixel map structure(s) contained within the PICT.
To examine these pixmaps, you’ll first need to install your own bitsProc, and then manually check the bounds, hRes, and vRes fields of any pixmap being passed. In most cases the hRes and vRes fields will be set to the Fixed value 0x00480000 (72 dpi); however, some applications will set these fields to the PICT’s actual resolution, as shown in the code below.
Revised by: Developer Support Center September 1993
Written by: Developer Support Center June 1993
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As in this Technical Note:
CWNewColorWorld CWord parameter
CMProfileResponse data structure
CWNewColorWorld CWorld parameter
Date Written: 2/22/93
Date reviewed: 7/2/93
Can I assume that the value of the ColorSync CWorld parameter returned by the CWNewColorWorld routine isn’t null if the routine was successful? I’d like to determine whether a color world exists by checking the variable for null.
___
You can assume that if no error is returned by CWNewColorWorld, the CWorld parameter will be a valid handle. In other words, it won’t be null if no error is returned.
CMProfileResponse data structure
Date Written: 3/18/93
Last reviewed: 6/24/93
How do I access fields within the CMProfile data structure?
___
Use the structures defined in the CMApplication.h file. These structures will allow you to directly access all fields up to the profileName. You can’t access the profileName directly because the CMProfileResponse record is variable size. You can determine the profileName by using the GetProfileName call. Likewise, the customData must also be accessed in this way by using the GetProfileAdditionalDataOffset call.
ColorSync documentation
Date Written: 2/8/93
Last reviewed: 4/1/92
Do you have any documentation that describes ColorSync in more detailed than “The ColorSync Utilities” on the Developer CD? I want to develop a ColorSync-aware printer driver and application.
___
The “ColorSync Utilities” document on the Developer CD is a preliminary draft. Apple is updating it to include more sample code and descriptive explanations. The final document will be included as a chapter in Apple’s forthcoming Inside Macintosh: QuickDraw reference, which will be available later this year.
“ColorSync: A Tuning Fork for Color,” in the February issue of Apple Direct, provides a ColorSync overview. Also, the Print Hints column in the June 1993 issue of develop, “ColorSync and Printing,” addresses ColorSync implementation issues for products such as yours.
How Apple Color Printer uses ColorSync
Date Written: 2/8/93
Last reviewed: 6/14/93
What’s the mechanism the Apple Color Printer driver uses for ColorSync?
___
The Apple Color Printer uses the low-level ColorSync color-matching calls to perform color matching in the print bottleneck routines. Thus, color matching happens before rendering so that rendering always occurs with matched colors. For more information, see the section called “What does a printer driver have to do?” in the Print Hints column of the June 1993 issue of develop.
ColorSync 1.0.2 fixes kNumColorsToMatch bug
Date Written: 1/20/93
Last reviewed: 6/14/93
I tried calling CMMatchColors with different numbers of colors to match; 10,000 worked fine, but 50,000 or greater crashed with a bus error. Is this a bug?
___
This is a bug in ColorSync 1.0 and 1.0.1. The “for” loop inside the Apple CMM uses a short rather than a long. It’s been fixed for version 1.0.2.
ColorSync responders
Date Written: 1/18/93
Last reviewed: 6/14/93
Which ColorSync responders can I rely on? The ColorSync cdev as I understand it yields the system responder. I don’t have anything else (for example, Color Printer driver); how do I get a monitor and printer responder?
___
The ColorSync documentation doesn’t discuss responders very well. A system profile responder is always available if ColorSync is installed. It can be used only to set the current system profile and to get the current system profile. A printer profile isn’t registered normally and has to be registered by the printer driver when requested to do so with a PrGeneral call.
For more information, please read “Syncing up with ColorSync” in issue 14 of develop.
MatchColors and profile handles for CMYK or RGB conversion
Date Written: 1/18/93
Last reviewed: 6/14/93
How do I get the right ProfileHandles to convert CMYK to RGB data and vice versa via the low-level MatchColors call? All routines now are returning “Responder errors” (-180 and -182), a description that doesn’t help much at the moment.
___
To convert CMYK to RGB, you need to have a proper source profile specifying that the data is in CMYK format (dataType = "CMYK"), and a proper destination profile specifying that the data is in RGB format (dataType = "RGB "). You can use ProfileMaker to modify a current profile (that is, 13" RGB) to create the CMYK format; or, you can also use the current system profile obtained by calling GetProfile.
QD 525 - LaserWriter Utility Q&As
QuickDraw
Revised by: Developer Support Center September 1993
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
SCSI drive format for LaserWriter II NTX with Rev. 3 ROMs
Date Written: 5/3/91
Last reviewed: 6/26/91
What could be causing intermittent PostScript errors from a LaserWriter II NTX with an SCSI hard disk mounted after installing the Rev 3 ROM upgrade?
___
The LaserWriter II NTX with Rev 3 ROMs does not work properly with a hard disk formatted with the LaserWriter Font Utility 1.x. You need to reformat the disk and copy the fonts back onto the hard disk using the LaserWriter Font Utility 2.0.2. Unfortunately, there is no way to make this procedure easier.
LaserWriter Font Utility copies Postscript file to printer
Date Written: 9/23/91
Last reviewed: 10/8/91
Is there a utility that will send a PostScript file from disk to the LaserWriter?
___
The LaserWriter Font Utility handles this job and is part of the System 7 disk set. On the System 7 Golden Master CD, the path is System 7.0: System Software 7.0: Installer Version: Tidbits folder.
QD 530 - Palette Manager Q&As
QuickDraw
Revised by: Developer Support Center September 1993
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As in this Technical Note:
GetNewPalette and default palette documentation update
GetNewPalette and default palette documentation update
Date Written: 3/10/93
Last reviewed: 6/24/93
Our application has a 'pltt' resource containing colors, which is replaced by the user’s palette from a Preferences file if it exists. Sometimes our Color dialog box displays black-and-white or incorrect colors. Does the Palette Manager documentation describe default palettes correctly? Should I call GetNewPalette(0) on my application resource fork instead of calling GetPalette(-1)?
___
The actual implementation of the Palette Manager is somewhat different than documented in Inside Macintosh Volume VI.
The Palette Manager has two levels of default palettes. First, there’s a system palette that’s loaded at system startup time. This system palette ('pltt', ID#0) is loaded from the system file if it exists and stored in the system heap along with other Palette Manager globals. Once the system is booted, this system palette doesn’t change. Even if you replace the palette in the system file, the new palette isn’t reloaded. If there’s no system palette resource in the system file, the Palette Manager hard codes a 2 entry (black and white) palette as the system palette. The default system file for both Systems 6.0.8 and 7.1 doesn’t have a ('pltt', ID#0) resource. Therefore, it seems that the default system palette is typically an entry palette with black and white.
The other level of default palette is the application palette. This palette is stored in a low-memory global called AppPalette. You probably won’t find it in any documentation, but the address is $DCC. (This low-memory global is switched during context switches so you don’t have to worry about losing the low-memory global when switching applications.) The Palette Manager loads this default application palette when InitPalette is called. Normally, you don’t call InitPalette directly in your code. Instead, InitWindows calls InitPalette for you. Inside InitPalette, a call to Get1Resource is made with ('pltt', ID#0). Get1Resource differs from GetResource because Get1Resource checks only the first resource file. Since your application is assumed to be at the top of the resource chain, this call will get a palette of ID #0 if it’s available in that file *only*. This actually causes a problem when running an application from a development environment such as Think C.
Unlike the default system palette, the default application palette can be modified by a call to SetPalette(WindowPtr(-1), newDefaultAppPalette, TRUE). You can also get the default palette with a call to GetPalette(WindowPtr(-1)). When there’s no application default palette, GetPalette(WindowPtr(-1)) uses the default system palette instead. As mentioned earlier, this is typically a 2 entry palette with black and white.
Lastly, the documentation for the call GetNewPalette on page 20-19 of Inside Macintosh Volume VI is completely misleading. GetNewPalette simply loads in the specified 'pltt' resource using GetResource and then detaches it with DetachResource to make it a handle. It doesn’t attach it to the current window. And, it doesn’t load the default application handle if the specified resource can’t be found.
SetPalette cUpdates, NSetPalette, and window update events
Date Written: 9/26/91
Last reviewed: 6/14/93
When I pass FALSE in the cUpdates parameter to SetPalette, I still get update events to that window when I modify its palette. What’s going on?
___
SetPalette’s cUpdates parameter controls whether color-table changes cause that window to get update events only if that window is not the frontmost window. If that window is the frontmost window, any changes to its palette cause it to get an update event regardless of what the cUpdates parameter is. When you call SetEntryColor and then ActivatePalette for your frontmost window, the window gets an update event because it’s the frontmost window even though you passed FALSE in the cUpdates parameter. Another important point is that windows that don’t have palettes always get update events when another window’s palette is activated.
Fortunately, system software version 6.0.2 introduced the NSetPalette routine, which is documented in the Macintosh Technical Note “Palette Manager Changes in System 6.0.2” and on page 20-20 in the Palette Manager chapter of Inside Macintosh Volume VI. This variation of SetPalette gives you the following options in controlling whether your window gets an update event:
• If you pass pmAllUpdates in the nCUpdates parameter, your window gets an update event when either it or another window’s palette is activated.
• If you pass pmFgUpdates, your window gets an update event when a palette is activated only if it’s the frontmost window (in effect, it gets an update event only if its own palette is activated).
• If you pass pmBkUpdates, your window gets an update event when a palette is activated only if it’s not the frontmost window (in effect, it gets an update event only if another window’s palette is activated).
• If you pass pmNoUpdates, your window never gets an update event from any window’s palette being activated, including that window itself.
Restoring Finder desktop colors after using Palette Manager
Date Written: 8/28/91
Last reviewed: 8/1/92
After using the Macintosh Palette Manager, how do I restore the Finder’s desktop colors?
___
The Finder desktop’s colors are restored automatically on quitting applications that use the Palette Manager. Colors aren’t restored automatically when switching from your application to another, but if that application needs a certain set of colors and uses the Palette Manager to get them, then it’ll have them the moment it comes to the front. If you’re concerned about applications that don’t use the Palette Manager, you can use RestoreDeviceClut(gd:GDHandle), passing the handle to the GDevice of the screen you want to reset, or nil if you want to reset all of your devices. Passing nil to RestoreDeviceClut is your best bet, as it is very straightforward, and resets all of your monitors. You may not wish to do this, however, because RestoreDeviceClut is only available on machines with 32-bit color QuickDraw.
To reset a screen’s GDevice for machines without 32-bit color QuickDraw, you will need to keep track of the color table.When your application starts up, get the GDevice’s color table and save it—you’ll need it later. This value can be found at (**(**GDHandle).gdPMap).pmTable, where gdPMap is a PixMapHandle, and pmTable is a CTabHandle which tells you the absolute colors for this image. These data structures are found in Inside Macintosh Volume V, pages 52 and 119.
Build your application’s “world” using the Palette Manager, and avoid low-level methods of changing colors. When your application is about to quit and you want to restore the environment to its original state, get the color table you saved in the beginning. Convert this to a palette using CTab2Palette. Then set your window to this palette with SetPalette. This will cause the environment to update to the original color table that you initially got from the GDevice. If the application that is behind your application is Palette Manager friendly, then it will restore the environment to its palette. You may also want to do this procedure at the suspend event, as shown in the DTS sample MacApp program, FracApp. One of the problems that you won’t be able to solve this way involves multiple monitors. You won’t know which one to update. Only the monitor that has the window that you’ve called ActivatePalette on will update.
If your application changes the color environment with the Palette Manager, then RestoreDeviceClut is called automatically when your application quits. This means that you shouldn’t have to worry about restoring the palette if you don’t want to. There is a catch, however (there always is). When you use the SADE version of MultiFinder (6.1b9), it prevents this from automatically happening. Other versions of MultiFinder don’t have this side effect.
RestoreDeviceClut and color flash when application quits
Date Written: 8/23/91
Last reviewed: 6/14/93
When my application, which uses a color palette, quits, there is momentary but distracting flash of weird colors in the Finder windows and the desktop temporarily appears in a weird color. Is there any way to get around this?
___
When you quit, RestoreDeviceClut is called to restore the color table and an update event is called to redraw the screen. It’s the delay between the change in the color table and the update event that causes the flash of incorrect colors to be displayed. This, unfortunately, is unavoidable.
Macintosh Palette Manager and offscreen graphics
Date Written: 7/22/91
Last reviewed: 8/1/92
The Macintosh Palette Manager doesn’t work on offscreen environments the way you’d expect. Unlike color windows, SetPalette will not change the offscreen’s color table; rather it just allows you to use PMForeColor and PMBackColor to set the current drawing color in that environment. To change the offscreen’s color table you’ll need to convert the palette to a color table and then set the resulting color table to the off screen. Calling Palette2CTab will do the converting for you.
To get around having to use palettes to define the current drawing color in the off screen, you can always use Index2Color and then RGBForeColor to get the color to be set for drawing. A remake of GiMeDaPalette code sample, available on the latest Developer CD Series disc, does offscreen drawing in place of having to continually copy a PICT.
QD 535 - Picture Utility Q&As
QuickDraw
Revised by: Developer Support Center September 1993
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
GetPictInfo and QuickTime compressed PICT files
Date Written: 2/24/92
Last reviewed: 8/1/92
Is it my imagination, or does GetPictInfo return a bit depth of 1 on QuickTime compressed PICT files?
___
Yep! This is what’s happening: The Picture Utilities Package doesn’t know of the QuickTime Compressed Pixmap opcode (0x8200), so it just skips over the opcode’s data; then it finds the PacksBitRect opcode containing the black-and-white pseudo-alert that you get when you draw the picture on a machine that doesn’t have QuickTime installed, and GetPictInfo reports back this alert.
Trivia: When QuickTime is installed, it displays the compressed image and then ignores the following PacksBitRect since QuickTime knows it’s only the black-and-white alert.
NewPalette doesn’t use CTab2Palette to create a palette
Date Written: 3/12/92
Last reviewed: 6/14/93
I’m using the Picture Utilities Package to extract the color table from a picture. After getting the color table, I use NewPalette to construct a palette from the color table (usage = tolerant, tolerance = 0). After I do this, the RGB values in the palette don’t always exactly match the RGB values in the source color table, causing my program to fail. If I use NewPalette without a source color table, and then use CTab2Palette to copy the colors over (again with usage = tolerant, tolerance = 0), the colors match exactly.
___
It turns out that NewPalette doesn’t use CTab2Palette, but copies the RGB fields in a strange way that’s causing the problems you’re seeing. NewPalette copies the high byte in each color table RGB entry into both the high byte and the low byte of the corresponding palette entry. Thus, if the color table entry for red was $F000, it becomes $F0F0. This of course makes no difference to QuickDraw since the low byte isn’t displayed, but if your program expects the low byte to match, that’s where your problem exists. CTab2Palette is different, in that it doesn’t copy the high byte into the low byte unless the pmAnimated bit is set.
The best solution for your code isn’t to compare the entire RGB value when comparing colors, but rather to compare the high byte of each RGB component separately. If this isn’t possible, the next best solution is for you to use the workaround that you’ve already discovered with CTab2Palette.
It’s unlikely that the Palette Manager is going to change in the future for something like this. In fact, we would almost call it a “feature” since other developers may even depend on it.
Spooling PixMaps to disk
Date Written: 6/10/91
Last reviewed: 10/22/91
Do you have sample code for spooling PixMaps to disk in PICT format? Should I write the PICT opcodes to the file myself?
___
Apple recommends that you do not try to write the PICT opcodes yourself. Instead, replace the PutPicProc bottleneck proc, as shown in the Color QuickDraw chapter of Inside Macintosh Volume V on page V-89.
Two additional samples can be found in the sample code contained in the Developer CDs. Look for: “Tools & Apps: Graphics and Imaging: PICT Stuff.” One is a program and the other is an FKEY; both dump the main screen to disk as a PICT. The FKEY is a more complete sample in the sense that it works in black and white as well as Macintosh color computers, but the other is a smaller and simpler sample.
Getting the color usage from a picture under System 6
Date Written: 6/8/92
Last reviewed: 9/15/92
Do you know how I can obtain the color table of a picture when using a system version that happens to be less than 7.0? The Picture Utilites package seems to be only implemented in System 7.0.
___
You’re correct; the Picture Utilities package is implemented only under System 7. However, it’s possible to write code to duplicate its functionality under System 6. Basically, what you want to do is parse a picture, looking at the colors used for the different objects. How you deal with the colors is up to you.
What you do is replace the QuickDraw bottlenecks in a GrafPort with procedures of your own; in all the bottlenecks for QuickDraw primitives, you can just record the current color as having been used for an object. When you get a StdBits opcode, you’ll have to parse the pixmaps, looking through the image and recording all the colors used. As a shortcut, you could just record all the colors in the color table of the pixmap, if it's an indexed pixel image. After collecting this list of colors and any information on how often they are used, it’s up to you to boil this down into useful information, depending on how you want to use it.
QD 540 - QuickDraw GX Q&As
QuickDraw
Revised by: Developer Support Center September 1993
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As for this month:
QuickDraw GX doesn’t replace QuickDraw
QuickDraw GX and QuickDraw accelerated display cards
QuickDraw GX doesn’t replace QuickDraw
Date Written: 12/11/92
Last reviewed: 7/2/93
Will QuickDraw and QuickDraw GX coexist, or will QuickDraw GX replace QuickDraw?
___
QuickDraw isn’t leaving with the introduction of QuickDraw GX. It’s here to stay. Among other reasons, QuickDraw functions are used extensively by the Macintosh Toolbox and applications. For more information, see the article “Getting Started With QuickDraw GX” in issue 15 of develop.
QuickDraw GX and QuickDraw accelerated display cards
Date Written: 6/16/92
Last reviewed: 7/2/93
Will display cards that offer QuickDraw acceleration be affected by QuickDraw GX?
___
Current QuickDraw acceleration cards aren’t affected by QuickDraw GX. QuickDraw GX doesn’t use any of the current QuickDraw calls and its presence won’t affect applications that use only QuickDraw. QuickDraw acceleration cards also won’t accelerate QuickDraw GX.
◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. WIQkWIQk +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d o < Ç– ( ú Z.QD 1 - 32-Bit QuickDraw: Version 1.2 Features
° d ONLN d / Å < ê á * QuickDraw
° d ONLN d : ú < ® q * Written by: ° d ONLN d F ú Ñ ® Œ )HGuillermo Ortiz ° d ONLN d V úÀ ®˛ ( ƒÈ
April 1990 ° d ONLN d a ¥ < ¿Á ( ‹ ZOThis Technical Note describes the changes and enhancements to 32-Bit QuickDraw ° d ONLN d ∞ ¥Á ¿˛ ( ‹from ° d ONLN d µ ¿ < à b ( Ë Zversion ° d ONLN d Ω ¿ b Ã˛ )&S1.0 (as shipped on the original Color Disk) to version 1.2, which ships with System ° d ONLN d à < ÿR ( Ù Z9Software 6.0.5 and later. This Note assumes familiarity ° d ONLN dJ ÃR ÿl ( Ùpwith ° d ONLN dO Ãl ÿø )Inside Macintosh ° d ONLN d_ Ãø ÿ˛ )S , Volume V, ° d ONLN dk ÿ < ‰E ( Z4Color QuickDraw, and 32-Bit QuickDraw release notes. X
° d ONLN d† < ∂ *432-Bit QuickDraw
° d ONLN d±$ <0® *GVersion 1.0 of 32-Bit QuickDraw shipped in May 1989 in response to the ° d ONLN d¯$®0˛ (LΔgrowing need for ° d ONLN d 0 << Z (X ZColor ° d ONLN d0 Z<˛ ) TQuickDraw support for direct color devices and pictures (PICT2) and video boards for ° d ONLN dd< <H y (d Z
large-screen ° d ONLN dq< yH˛ )=Mmonitors which require 32-bit addressing for black and white operation. This ° d ONLN døH <T (p Z]original version of 32-Bit QuickDraw was a separate file that had to be copied manually into ° d ONLN d HT˛ (pthe ° d ONLN d T <` (| Z-System Folder. With the introduction of the ° d ONLN dMT`˛ )‘/Macintosh IIci, Apple put 32-Bit QuickDraw into ° d ONLN d}` <là (à ZPROM. Now System Software 6.0.5 and later offer 32-Bit QuickDraw as an integral ° d ONLN dÕ`Ãl˛ (àÍ part of the ° d ONLN dŸl <xÉ (î ZASystem Software which can be installed by the standard Installer ° d ONLN dlÉx˛ (î°(although the file is still ° d ONLN d6x <Ñ j († Z
separate). ° d ONLN dAê <ú n *
This Note ° d ONLN dKê nú˛ )2Ndescribes the changes and enhancements in version 1.2 of 32-Bit QuickDraw from ° d ONLN döú <® Õ (ƒ Z version 1.0. Beginning with ° d ONLN d∑ú Õ®˛ )ë>version 1.2, QuickDraw functionality is identical on all Color ° d ONLN dˆ® <¥ ˆ (– Z&QuickDraw machines, including all the ° d ONLN d ® ˆ¥˛ )∫3performance improvements which were originally only ° d ONLN dP¥ <¿ ∂ (‹ Zavailable in the IIci ROM.
° d ONLN dkÿ <ÁB *'%New Features (In No Particular Order)
° d ONLN dëÛ <ˇ *#PICTs Contain Font Name Information ° d ONLN dµ < *&Every time you draw text inside of an ,
Courier ° d ONLN d€ d )‘ _OpenPicture ° d ONLN dÁ dÖ )T and ° d ONLN dÏ Ö‡ )!
_ClosePicture ° d ONLN d˘ ‡˛ )[ pair, ° d ONLN d <$E (@ Z7QuickDraw stores the name of the current font and uses ° d ONLN d7E$˛ (@c&it when playing back the picture. The ° d ONLN d^$ <0ë (L ZIopcode used to save this information is $002C and its data is as follows:
° d ONLN d®< <G π * PictFontInfo = Record ° d ONLN d¬F <Qü *
G length : Integer; { length of data in bytes } ° d ONLN d
P <[ü *
G fontID : Integer; { ID in the source system } ° d ONLN dRZ <e ˇ *
' fontName : Str255; ° d ONLN dzd <o Ø *
END; ¡ X¡
*K.QD 1 - 32-Bit QuickDraw: Version 1.2 Features (÷1 ) of 5 (Ï ZM.QD.32BitQuickDraw ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø˛ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) ¢ *QuickDraw only saves this ° d ONLN d ¢ )⁄ )ä;information one time for each font used in a picture. When ° d ONLN d V * 6 æ ( R 6#QuickDraw plays back a picture, it ° d ONLN d y * æ 6 È )¶ uses the ,
Courier ° d ONLN d Ç ) È 5 )+fontID ° d ONLN d à * 6⁄ )*+ as a reference into the list of font names ° d ONLN d ¥ 6 B* ( ^ 6<which are used to set the correct font on the target system. ° d ONLN d Ò N Z µ * For example, the following code:
° d ONLN d f qv *F GetFNum('Venice', theFontID); { Set a font before opening PICT} ° d ONLN dY p { ê *
TextFont(theFontID); ° d ONLN dr Ñ è — *% pHand2 := OpenPicture (pictRect); ° d ONLN dò é ô Ü *
MoveTo(20,20); ° d ONLN dØ ò £ ‡ *
( DrawString(' Better be Venice'); ° d ONLN dÿ ¨ ∑ — *% GetFNum('Geneva', theFontID); ° d ONLN d˛ ∂ ¡ § *
H TxFont 'geneva' /* second Geneva does not ° d ONLN d∫Ë Ûä *
J need another $002C guy */ ° d ONLN dÚ ˝ ï *
DVText {20, "Geneva"}
° d ONLN d • *VThis feature works regardless of the type of picture being saved, including old style ° d ONLN du•⁄ (0√
PICTs in a ° d ONLN dÄ ! ¥ (= 6 black and white port. Using ° d ONLN dù ¥ )ú
_OpenCPicture ° d ONLN d™!O )[ instead of ° d ONLN d∂O £ )@ _OpenPicture ° d ONLN d¬£!⁄ )T to start a ° d ONLN dŒ! - (I 64recording session results in the same functionality. ° d ONLN d9 E ˛ *&Direct PixPat Structures Now Supported ° d ONLN d*R ^ *3QuickDraw now supports 16-bit and 32-bit per pixel ° d ONLN d]Q]= )˚PixPat ° d ONLN dcR=^u )*
*C2 ) of 5 )˘.QD 1 - 32-Bit QuickDraw: Version 1.2 Features +dM.QD.32BitQuickDraw ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -
April 1990 / X /
° d ONLN d ) < 5 ( Q Z%Direct 'cicn' Resources Now Supported ° d ONLN d & B < N7 *3QuickDraw now supports 16-bit and 32-bit per pixel ,
Courier ° d ONLN d Y A7 Ma )˚'cicn' ° d ONLN d _ Ba N˛ )*! resources. The 16-bit per pixel ° d ONLN d Å O < [n ( w ZDis particularly cool since you save the space required for an 8-bit ° d ONLN d ≈ Nn Zò ( wå'clut' ° d ONLN d À Oò [ú )*. ° d ONLN d Õ g < sΩ ( è Z<GWorlds Can Now Be Allocated in MultiFinder Temporary Memory ° d ONLN d
Ä < å S *You ° d ONLN d Ä S å æ )can now use the new ° d ONLN d" æ ã )k
useMFTempBit ° d ONLN d/ Ä ås )\(bit 2) in a call to ° d ONLN dD s ã≤ )Y NewGWorld ° d ONLN dM Ä≤ å˛ )? as an option to ° d ONLN d^ å < ò/ ( ¥ Z1allocate pixels in MultiFinder temporary memory. ° d ONLN dè å/ ò˛ )Û) In addition, you can now allocate screen ° d ONLN dπ ò < §˛ ( ¿ Z]buffers in MultiFinder temporary memory using the following routine, defined in Pascal and C:
° d ONLN d ∞ < ªã *CFUNCTION NewTempScreenBuffer (globalRect: Rect; purgeable: BOOLEAN; ° d ONLN d[ ∫ < ≈, *
° d ONLN de* <6 ‚ * Indexed to Indexed Dithering ° d ONLN dÇB <N { * _CopyBits ° d ONLN dãC {O ñ )? now ° d ONLN dêC ñO ’ )
supports the ° d ONLN dùB ’N )?
ditherCopy ° d ONLN dßCO˛ )F. transfer mode whenever the destination device ° d ONLN d÷O <[7 (w Z7is between one and eight bits per pixel, regardless of ° d ONLN d
O7[˛ )˚)the depth of the source image. With this ° d ONLN d7[ <gä (É ZFsupport, an eight-bit image can now be approximated on a one-bit or a ° d ONLN d}[äg˛ (É®four-bit device by using ° d ONLN dñg <sÕ (è ZXerror diffusion. Furthermore, an eight-bit image could also be dithered to a different ° d ONLN dÓgÕs˛ (èÎ
set of 256 ° d ONLN d˘s <ù (õ ZNcolors or a four-bit image could be dithered to an eight-bit device that does ° d ONLN dGsù˛ (õªnot have the desired ° d ONLN d\ <ã ] (ß Zcolors. ° d ONLN ddó <£ *"32-Bit Addressed PixMap Structures ° d ONLN dá∞ <º § *Version 1.2 defines a ° d ONLN dù∞ §º º )hnew ° d ONLN d°Ø ºª ˚ ) pmVersion ° d ONLN d™∞ ˚º )? ( ° d ONLN d¨Øªg )baseAddr32 = 4 ° d ONLN d∫∞gºΔ )d) for 32-bit pointer ° d ONLN dœØΔª˛ )_baseAddr ° d ONLN dÿΩ <… ( Z
values. The ° d ONLN dº » ∑ )CbaseAddr ° d ONLN dÌΩ ∑… Ê )8 of such ° d ONLN dˆº Ê» )/PixMap ° d ONLN d¸Ω…≥ )*# structures is treated as a 32-bit ° d ONLN d Ω≥…˛ )£address, so no ° d ONLN d.… <’ú (Ò ZJstripping or address translation is performed on it in 32-bit mode. This ° d ONLN dx…ú’˛ (Ò∫is a specially useful ° d ONLN dé÷ <‚ Ë (˛ Z#feature when the base address of a ° d ONLN d±’ Ë· )¨PixMap ° d ONLN d∑÷‚ )* ° d ONLN d∏÷‚r )points to a NuBus
° d ONLN d…‘rflz (˚ê™
° d ONLN d ÷z‚˛ + address, for example in a ° d ONLN d‚ <Ó ü (
Zvideo grabber board. ° d ONLN d˙˚ < x * A new call, ° d ONLN d˙ x ≈ )< Pixmap32Bit ° d ONLN d˚ ≈ )M, is now available ° d ONLN d$˚ à )Zto inquire if a given ° d ONLN d:˙à≤ )iPixMap ° d ONLN d@˚≤˛ )* requires 32-bit ° d ONLN dQ < s (/ Z addressing.
° d ONLN d] <*' */FUNCTION Pixmap32Bit(pmh:pixMapHandle):Boolean; ° d ONLN dç) <4c *
% } ° d ONLN d "Q <\ *,pascal BOOLEAN Pixmap32Bit(pixMapHandle pmh) ° d ONLN d O[ <f ı *
% = {0x203C,0x0004, 0x0016,0xAB1D}; ¡ X¡
*T.QD 1 - 32-Bit QuickDraw: Version 1.2 Features (÷3 ) of 5 (Ï ZM.QD.32BitQuickDraw ˇr ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 5 ª *$Updated GetPixBaseAddress ° d ONLN d B N Ä *Version 1.2 updates ,
Courier ° d ONLN d . A Ä M ˜ )hGetPixBaseAddress ° d ONLN d ? B ˜ Ng )w to return the address ° d ONLN d V Bg Né )pof any ° d ONLN d ] Aé M∏ )'PixMap ° d ONLN d c B∏ N⁄ )*. The ° d ONLN d j O [G ( w 6@routine does the right address translation or stripping for all ° d ONLN d ™ NG Zq ( wePixMap ° d ONLN d ∞ Oq [v )* ° d ONLN d ± Ov [⁄ )structures, including ° d ONLN d « \ h c ( Ñ 6screen devices, ° d ONLN d ◊ \ c h. )K'unlocked GWorlds, and 32-bit addressed ° d ONLN d ˛ [. gX )ÀPixMap ° d ONLN d \X h⁄ )* structures. The address it ° d ONLN d! i u G ( ë 6 returns is ° d ONLN d, i G uO )/6only valid in 32-bit addressing mode. Also unless the ° d ONLN db hO ty ( ëmPixMap ° d ONLN dh iy u⁄ )* is locked and made ° d ONLN d| v Ç œ ( û 6%unpurgeable, the address returned by ° d ONLN d° u œ ÅF )∑GetPixBaseAddress ° d ONLN d≤ vF ÇV )w is ° d ONLN d∂ vV Ç⁄ ) only valid until any call to ° d ONLN d” Ç é æ ( ™ 6!QuickDraw or the toolbox is made. ° d ONLN dı ö ¶ Õ * _CopyBits from Screen Devices ° d ONLN d ≥ ø *4The picture recording mechanism has changed so that ° d ONLN dG ≥ øL )ˇ if you call ° d ONLN dS ≤L æã )5 _CopyBits ° d ONLN d\ ≥ã ø⁄ )? while recording ° d ONLN dm ¿ à é ( Ë 6a picture with the source ° d ONLN dá ø é À ∏ )vPixMap ° d ONLN dç ¿ ∏ à ‡ )* being a ° d ONLN dñ ¿ ‡ Ã⁄ )(5screen device, the data is correctly accumulated into ° d ONLN dÃ Õ Ÿ* ( ı 6>the picture. Note that if the screen being copied is not the ° d ONLN d
∫ *New Picture Recording Trap ° d ONLN dæ # x *Version 1.2 adds a ° d ONLN d— x# ™ )`
new call, ° d ONLN d€ ™" )2
_OpenCPicture ° d ONLN dË#⁄ )[-, to create pictures that contain information ° d ONLN d# / Ù (K 60regarding the native resolution of the recorded ° d ONLN dF# Ù/⁄ )‹-image. When QuickDraw draws this picture, it ° d ONLN dt/ ;† (W 6Qscales the image to the resolution of the target device. Applications that need ° d ONLN d≈/†;⁄ (Wæ to scale the ° d ONLN d“; G ˚ (c 61images directly can also access this information.
° d ONLN dS ^? *;FUNCTION OpenCPicture(VAR CPictInfo:CPictRecord):PicHandle; ° d ONLN d@] h m *
INLINE $AA20; ° d ONLN dRq |! *5pascal PicHandle OpenCPicture(CPictRecord *CPictInfo) ° d ONLN dà{ Ü ^ *
Size in bytes ° d ONLN d˘ √) „ )cName ° d ONLN d˛ /)p )l Description H |Hµ ° d ONLN d + 7 Ö (S ù2 ° d ONLN d
* √6 Ù )DpicSize ° d ONLN d+ 7ê )Zlow word of picture size ° d ONLN d/8 D Ö (` ù8 ° d ONLN d17 √C ˚ )DpicFrame ° d ONLN d:8 Dã )Zbounding box at 72 dpi c |cµ ¡ 4¡˘
(÷ 64 ) of 5 )˘.QD 1 - 32-Bit QuickDraw: Version 1.2 Features +dM.QD.32BitQuickDraw ˇJ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -
April 1990 / X /
° d ONLN d ) ` 5 ¥ ( Q ~Picture Header T | TÁ ° d ONLN d 7 ` C f *2 ,
Courier ° d ONLN d 6 ç B ” )-
version op ° d ONLN d 7 Cc )cversion opcode = $0011 ° d ONLN d 3 D ` P f ( l ~2 ° d ONLN d 5 C ç O æ )-version ° d ONLN d = D Pg )cversion number = $02FF ° d ONLN d T Q ` ] f ( y ~2 ° d ONLN d V P ç \ Ã )- Header op ° d ONLN d ` Q ]d )cheader opcode = $0C00 ° d ONLN d w ^ ` j f ( Ü ~2 ° d ONLN d y ] ç i æ )-version ° d ONLN d Å ^ jl )c-2 for PICTs created with ° d ONLN d õ ]l i« )|
í ` û f ( ∫ ~8 ° d ONLN d ë ç ù æ )-SrcRect ° d ONLN d í û[ )cnative source rectangle ° d ONLN d, ü ` ´ f ( « ~4 ° d ONLN d. û ç ™ ≈ )-reserved | Á ° d ONLN d7 ≈ < — ( Ì Z,The following is a sample PICT created with ° d ONLN dc ƒ –m )÷
_OpenCPicture ° d ONLN dp ≈m —p )[:
° d ONLN dr › < Ëö ( ZF 00 48 /* low word of size */ ° d ONLN dπ Á < Úö *
F 00 00 00 00 00 7D 00 7D /* picFrame at 72 dpi */ ° d ONLN d Ò < ¸ö *
F 00 11 /* PICT version opcode */ ° d ONLN dG ˚ <ö *
F 02 FF /* version number */ ° d ONLN dé <ö *
F 0C 00 /* PICT header Opcode */ ° d ONLN d’ <ö *
F FF FE /* PICT version -2 */ ° d ONLN d <$ö *
F 00 00 /* reserved */ ° d ONLN dc# <.ö *
F 01 20 00 00 /* HRes (Fixed) */ ° d ONLN d™- <8ö *
F 01 20 00 00 /* VRes (Fixed) */ ° d ONLN dÒ7 <Bö *
F 00 00 00 00 01 F4 01 F4 /* picFrame at native resolution */ ° d ONLN d8A <Lö *
F 00 00 00 00 /* reserved */ ° d ONLN dK <Vö *
F /* picture data follows */ ° d ONLN dΔU <`ö *
F 00 FF /* end of picture opcode */
° d ONLN d
w <Ü õ *& Random Notes
° d ONLN dí <û ‡ * For information on bug fixes in ° d ONLN d:í ‡û˛ )§5the System Software 6.0.5 release of 32-Bit QuickDraw ° d ONLN dpû <™≈ (Δ ZR(version 1.2), please refer to the System Software 6.0.5 Change History, which is ° d ONLN d¬û≈™˛ (Δ„ available on ° d ONLN dœ™ <∂ (“ Z&the Developer CD Series, AppleLink in ° d ONLN dı™∂˛ )»0the Developer Services Bulletin Board (Developer ° d ONLN d&∂ <¬ û (fi ZServices: Macintosh ° d ONLN d:∂ û¬˛ )bEDeveloper Technical Support: System Software), and the Apple FTP site ° d ONLN dĬ <Œ (Í Z/on the Internet in the ~ftp/pub/dts/sw.license. ° d ONLN d∞€ <Á *,Note that the dispatching mechanism for the ° d ONLN d‹€Á. )Ÿnew ° d ONLN d‡⁄.ÊÇ ) _QDOffscreen ° d ONLN dÏ€ÇÁ˛ )T calls is slightly different ° d ONLN d Ë <Ù Ë ( Z#than previously documented; it now ° d ONLN d,Ë ËÙ† )¨&requires that the high word passed in ° d ONLN dRÁ†ÛÆ )∏D0 ° d ONLN dTËÆÙ˛ ) contain the total ° d ONLN dgÙ < ¸ ( Z*length of the parameters (in bytes). The ° d ONLN dëÙ ¸ ˛ )¿8reason for this change is that if the call is made in an ° d ONLN d < V (( Z:earlier version of 32-Bit QuickDraw, the system can strip ° d ONLN d V ˛ ((t!the parameters from the stack and ° d ONLN d&
< [ (5 Zreturn ° d ONLN d- [ å ) QDError ° d ONLN d4
å= )1) set to the caller (instead of crashing). ° d ONLN d^= <I ¶ (e ZFurther Reference: h Xh ° d ONLN dqJ NV R +
• ° d ONLN dsJ `V ± )Inside Macintosh ° d ONLN dÉJ ±VC )Q, Volume V, Color QuickDraw ° d ONLN düV Nb R (~ l• ° d ONLN d°V `bm )432-Bit QuickDraw Release Notes (available from APDA) ° d ONLN d÷b Nn R (ä l• ° d ONLN dÿb `n )$System Software 6.0.5 Change History ° d ONLN d˝n Nz R (ñ l• ° d ONLN dˇn `z ó )
d e v e l o p ° d ONLN d n óz æ )7 , Issue I ° d ONLN d Ü <í (Æ Z*NuBus is a trademark of Texas Instruments. ¡ X¡
*(.QD 1 - 32-Bit QuickDraw: Version 1.2 Features (÷5 ) of 5 (Ï ZM.QD.32BitQuickDraw ˇf ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < ÅÈ ( õ Z)QD 2 - BitMapToRegion : So Many Bitmaps, ° d ONLN d ) nÈ Å˛ ( õSo ° d ONLN d , Ä < ì ô ( ≠ Z Little Time
° d ONLN d 8 í < ° á * QuickDraw
° d ONLN d C ≠ < π t * Revised by: ° d ONLN d O ≠ Ñ π ¿ )H Rich Collyer ° d ONLN d \ ≠¥ π˛ ( ’“
December 1989 ° d ONLN d j π < ≈ q ( · Z Written by: ° d ONLN d v π Ñ ≈ ¥ )H
Rick Blair ° d ONLN d Å πÀ ≈˛ ( ·È
April 1988 ° d ONLN d å “ < fi T ( ˙ ZThis ° d ONLN d ë “ T fi )%Technical Note discusses the routine ,
Courier ° d ONLN d ∂ — ›j )¥BitMapToRegion ° d ONLN d ƒ “j fi˛ )b , which converts a bitmap to a ° d ONLN d „ fi < ÍÎ ( ZXregion, and is available in the 32-Bit QuickDraw INIT and from Apple Software Licensing. ° d ONLN d< Í < ˆ Á * Changes since October 1989: ° d ONLN dW Í Á ˆ‡ )´2 Added trap definitions for developers using the ° d ONLN dâ ͇ ˆ˛ )˘32-Bit ° d ONLN dê ˆ <í ( ZGQuickDraw version of this routine without the correct MPW include file. - X- ° d ONLN dÿ <'á *%GThe following routine is now available to convert a bitmap to a region:
° d ONLN d 3 <>r *>FUNCTION BitMapToRegion(region:RgnHandle; bMap:BitMap): OSErr;
° d ONLN d_I <U S *in C:
° d ONLN dea <lc *;pascal OSErr BitMapToRegion(RgnHandle region, BitMap bMap);
° d ONLN d°w <Éò *JIf you are using the 32-Bit QuickDraw version of this routine without the ° d ONLN dÎwòɲ (ü∂correct MPW include ° d ONLN dˇÉ <è` (´ Z@file, then you need to include one of the following definitions: ° d ONLN d@õ <ß Z *Pascal
° d ONLN dG≥ <æÅ *AFUNCTION BitMapToRegion (region: RgnHandle; bMap: BitMap): OSErr; ° d ONLN dâΩ <» ™ *
INLINE $A8D7;
° d ONLN d†” <fl D *C
° d ONLN d¢Î <ˆÜ *Bpascal OSErr BitMapToRegion (RgnHandle region, const BitMap *bMap) ° d ONLN dÂı < ™ *
= 0xA8D7;
° d ONLN d¸ < k *Assembly
° d ONLN d# <. **_BitMapToRegion OPWORD $A8D7
° d ONLN d0: <F á *The region will ° d ONLN d@: áF )K!be built so that all one bits in ° d ONLN da9E5 )íbMap ° d ONLN de:5F˛ ) , are inside the region and all zero bits are ° d ONLN díF <R x (n Zoutside of it. ° d ONLN d°_ <k4 *3As with all QuickDraw calls which change a region, ° d ONLN d‘^4jù )¯BitMapToRegion ° d ONLN d„_ùkΔ )i requires ° d ONLN dÏ_Δk˛ )) you to pass ° d ONLN d¯l <x (î Z*an existing region (originally created by ° d ONLN d"k w1 )ƒ_NewRgn ° d ONLN d)l1xÅ )1). If the region ° d ONLN d;lÅx˛ )Pcannot be built due to an ° d ONLN dUx <Ñò († ZJinsufficient heap space or a size greater than 32K, then the routine will ° d ONLN düxòÑ˛ (†∂return an appropriate ¡ X¡
(÷ Z7QD 2 - BitMapToRegion : So Many Bitmaps, So Little Time (÷1 ) of 2 (Ï ZM.QD.BitMapToRegion ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† øˆ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d )≠ *Uerror code and the region will be empty. If the region would have exceeded 32K, the ° d ONLN d U ≠ )⁄ ( EÀ
In addition, ° d ONLN döDPr )>BitMapToRegion ° d ONLN d®ErQ⁄ )b offers new features. ° d ONLN døQ ] v (y 6You can now pass ° d ONLN d–Q v]⁄ )^Ea one-bit pixelmap which has been coerced to a bitmap. If you pass a ° d ONLN d^ j ˚ (Ü 61pixelmap which is too large, then you will get a ° d ONLN dG] ˚ik )„pixmapTooDeepErr ° d ONLN dW^kjè )p (-148) ° d ONLN d_^èj⁄ )$error. You can ° d ONLN dok w W (ì 6also pass the ° d ONLN d}j Wv è )?portBits ° d ONLN dÖk èwä )84 of a window, much like you would do with a call to ° d ONLN dπjäv… )˚ _CopyBits ° d ONLN d¬k…wÕ )?. ° d ONLN dƒÉ è? (´ 6>There is a potential problem with this routine, since MPW 3.1 ° d ONLN dÉ?è⁄ (´]!include files contain information ° d ONLN d$ê ú ◊ (∏ 6%about 32-Bit QuickDraw. If you want ° d ONLN dIè ◊õ9 )øBitMapToRegion ° d ONLN dWê9ú= )b ° d ONLN dXê=ú⁄ ) to be available on all machines, ° d ONLN dyú ® ß (ƒ 6 then you must use the object ° d ONLN dñú ß®⁄ )è;file from Software Licensing. The problem is that when you ° d ONLN d“® ¥í (– 6Mcompile your application with MPW 3.1 or later, the 32-Bit QuickDraw version ° d ONLN d ®í¥⁄ (–∞gets preference ° d ONLN d/¥ ¿ ê (‹ 6over the object file. You ° d ONLN dJ¥ ê¿ ´ )xmust ° d ONLN dN¥ ´¿ ˇ ) comment out the ° d ONLN d_¥ ˇ¿⁄ )T/routine in the include files if you want to use ° d ONLN dè¡ Õ Å (È 6the object file. If you ° d ONLN d®¡ ÅÕ Ì )ionly care about using ° d ONLN dæ¿ ÌÃO )lBitMapToRegion ° d ONLN dáOÕ⁄ )b on machines running 32-Bit ° d ONLN dËÕ Ÿ Ë (ı 6)QuickDraw, then you need not do anything. ¡ 4¡˘
*·2 ) of 2 )ƒ7QD 2 - BitMapToRegion : So Many Bitmaps, So Little Time +ñM.QD.BitMapToRegion ˇ™ ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. WIQkWIQk +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN dˇˇ ( ú Z-QD 3 - Color Cursor Cursing : A Leading Cause
° d ONLN dˇˇ * QuickDraw
° d ONLN dˇˇ * Revised by: ° d ONLN dˇˇ )H
Alan Mimms ° d ONLN dˇˇ ( ƒ‹ October 1989 ° d ONLN dˇˇ ( – Z Written by: ° d ONLN dˇˇ )H
Alan Mimms ° d ONLN dˇˇ ( –Î June 1989 ° d ONLN dˇˇ ( Ë ZIWorking with color cursors you create from scratch can cause headaches. ° d ONLN dˇˇ ( ˪This Technical Note ° d ONLN dˇˇ ( Ù Zmay help a bit. ° d ONLN dˇˇ *
Changes since June 1989: ° d ONLN dˇˇ )ì" Added a warning about purgeable ,
Courier ° d ONLN dˇˇ )®'clut' ° d ONLN dˇˇ )* resources. X ° d ONLN dˇˇ (& Z'If you’re building an application that ° d ONLN dˇˇ )µ4creates color cursors, you may encounter some quirks ° d ONLN dˇˇ (2 ZOpresent in Color QuickDraw that manifest themselves in hard-to-understand ways. ° d ONLN dˇˇ *If your cursor is, say, 15 ° d ONLN dˇˇ )Ä@pixels tall and 9 pixels wide, you might be tempted to use these ° d ONLN dˇˇ (W Zvalues for the ° d ONLN dˇˇ )F
bounds.bottom ° d ONLN dˇˇ )[ and ° d ONLN dˇˇ ) bounds.right ° d ONLN dˇˇ )T, respectively, ° d ONLN dˇˇ )Hin your cursor’s pixel ° d ONLN dˇˇ (c Zmap. ° d ONLN dˇˇ ) Don’t ° d ONLN dˇˇ ) . The problem is that when ° d ONLN dˇˇ )Ö3the cursor’s image needs to be expanded (i.e., when ° d ONLN dˇˇ (o Zyou ° d ONLN dˇˇ )Wspecify a two bit-per-pixel cursor and the mouse pointer is on an eight-bit screen) the ° d ONLN dˇˇ (| Z _SetCCursor ° d ONLN dˇˇ )M trap rounds the ° d ONLN dˇˇ )M=width of the pixel map in such a way that you’ll get only the ° d ONLN dˇˇ (à Zspace ° d ONLN dˇˇ ) Rrequired for a 15 by 8 pixel map allocated for the expanded cursor data. When the ° d ONLN dˇˇ (î Z%cursor’s image is expanded into this ° d ONLN dˇˇ )≠8too-small expanded cursor data handle as a 15 by 9 pixel ° d ONLN dˇˇ († Z-map, something in your heap will get munched. ° d ONLN dˇˇ *The cure is simple.
° d ONLN dˇˇ )çMake ° d ONLN dˇˇ )*certain ° d ONLN dˇˇ )&! that you always specify that the ° d ONLN dˇˇ (≈ ZpixmapHandle^^.bounds ° d ONLN dˇˇ )ì be 16 by 16. ° d ONLN dˇˇ )L This will cause ° d ONLN dˇˇ )Y _SetCCursor ° d ONLN dˇˇ )M to properly ° d ONLN dˇˇ (— Zallocate the expanded data ° d ONLN dˇˇ )ÅAarea, and all will be well in the land. Since the amount of data ° d ONLN dˇˇ (fi Zdrawn ° d ONLN dˇˇ )# for ° d ONLN dˇˇ )7a cursor is specified by the cursor’s pixel values and ° d ONLN dˇˇ (fiï'clut' ° d ONLN dˇˇ )* resource, trying to ° d ONLN dˇˇ (Í ZFsave a few bytes by making the bounds rectangle smaller than 16 by 16 ° d ONLN dˇˇ (ͪwouldn’t have been ° d ONLN dˇˇ (ˆ Zvery helpful anyway. ° d ONLN dˇˇ *;Another potential problem is with the color cursor’s color ° d ONLN dˇˇ (u#table. If you load the color table ° d ONLN dˇˇ ( Zfrom ° d ONLN dˇˇ )a ° d ONLN dˇˇ )
'clut' ° d ONLN dˇˇ )* resource using ° d ONLN dˇˇ )Q
_GetCTable ° d ONLN dˇˇ )F , you should make sure that the ° d ONLN dˇˇ )•'clut' ° d ONLN dˇˇ )* is ° d ONLN dˇˇ (' Z,marked non-purgeable while the color cursor ° d ONLN dˇˇ )›/is in use. If you do not take this precaution, ° d ONLN dˇˇ (4 Zbombs will occur if your ° d ONLN dˇˇ )x'clut' ° d ONLN dˇˇ )*$ gets purged at in inopportune time. ¡ X¡
(÷ ZQD 3 -
) &Color Cursor Cursing : A Leading Cause
(÷1 ) of 1 (Ï ZM.QD.ColorCursorCursing ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø4 ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < ÅR ( õ Z QD 4 - Colorizing With CopyBits
° d ONLN d Ä < è á * QuickDraw
° d ONLN d + õ < ß q *
Revised by ° d ONLN d 7 õ≈ ߲ ( √„
March 1988 ° d ONLN d B ß < ≥ q ( œ Z Written by: ° d ONLN d N ß Ñ ≥ ≈ )H
Chris Derossi ° d ONLN d \ ß± ≥˛ ( œœ
November 1987 ° d ONLN d j ø < À ¿ ( Á ZInside Macintosh Volume V ° d ONLN d É ø ¿ ÀQ )Ñ states that the foreground and ° d ONLN d £ øQ À˛ )ë#background colors are applied to an ° d ONLN d « à < ÿ Ö ( Ù Zimage during a ,
Courier ° d ONLN d ÷ À Ö ◊ Ω )ICopyBits ° d ONLN d fi Ã Ω ÿ Õ )8 or ° d ONLN d ‚ À Õ ◊ )CopyMask ° d ONLN d Í Ã ÿá )8 call. Accidental use of this ° d ONLN d Ãá ÿ˛ )Çfeature can create bizarre ° d ONLN d# ÿ < ‰ˆ ( Z\coloring effects. This note explains what happens, how to avoid problems, and how to use it. X
° d ONLN dÄ < ô *4 What Happens
° d ONLN dç$ <0 Æ *Color QuickDraw has a ° d ONLN d£$ Æ0˛ )rDfeature that will allow you to convert a monochrome image to a color ° d ONLN dË1 <= ã (Y Zimage. During a ° d ONLN d¯0 ã< √ )OCopyBits ° d ONLN d 1 √= Δ )8 ° d ONLN d1 Δ= ‘ )or ° d ONLN d0 ‘< )CopyMask ° d ONLN d 1 =˛ )82 call, if the foreground and background colors are ° d ONLN d?= <I‘ (e ZTnot black and white, respectively, Color QuickDraw performs the following operation ° d ONLN dì=‘I˛ (eÚon every ° d ONLN dúI <U ï (q Zpixel being copied:
° d ONLN d±b `m +$%NOTE: color table index = pixel value ° d ONLN dÿv `Å *%s = color table index of source pixel ° d ONLN dˇÄ `ã2 *
*fg = color table index of foreground color ° d ONLN d+ä `ï2 *
° d ONLN d⥠<¿0 (‹ Z3If your source image contains only black and white ° d ONLN dº¥0¿˛ )Ù*pixels, then all black pixels would become ° d ONLN dÁ¿ <ÃF (Ë Z7the foreground color and all white pixels would become ° d ONLN d ¿FÃ˛ (Ëd%the background color. This is because ° d ONLN dDà <ÿ◊ (Ù Z]the color table index for white is all zeros and the color table index for black is all ones. ° d ONLN d¢Â <Òm *>For example, suppose your source image was a 4-bit deep color ° d ONLN d‡‰mó (
ãPixMap ° d ONLN dÊÂóÒû )*. ° d ONLN dËÂûÒ˛ )Then the color table ° d ONLN d˝Ò <˝” ( ZWindex for white (in binary) is 0000 and the index for black is 1111. And let’s suppose ° d ONLN dTÒ”˝˛ (Ò that your ° d ONLN d^˝ < Û (% ZXforeground color is green with an index of 1101 while your background color is red with ° d ONLN d∂˝Û ˛ (%an ° d ONLN dπ <ë (1 ZGindex of 0011. Then for the black pixels, the above procedure produces:
° d ONLN d! `,á +$;ColoredPixelValue = (NOT(1111) AND 0011) OR (1111 AND 1101) ° d ONLN d?+ `6á *
; 1101 = ( 0000 AND 0011) OR (1111 AND 1101)
° d ONLN d{A <M (i Z-And the operation on the white pixels yields:
° d ONLN d™Z `eá +$;ColoredPixelValue = (NOT(0000) AND 0011) OR (0000 AND 1101) ° d ONLN dÁd `oá *
; 0011 = ( 1111 AND 0011) OR (0000 AND 1101) ¡ X¡
(÷ Z QD 4 - Colorizing With CopyBits (÷1 ) of 3 (Ï ZM.QD.ColorizingWithCopyBits ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø‹ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d , ë *Possible Problems
° d ONLN d 8 DG *AThis colorizing will only work on 2-color (i.e. black and white) ° d ONLN d S 8G D⁄ ( `e images, and then only if those ° d ONLN d r D P Ñ ( l 6colors occupy the first ° d ONLN d ä D Ñ P⁄ )lKand last entries in the color table. Trying to colorize colors that are not ° d ONLN d ÷ P \F ( x 6Ethe first and last color table entries will yield unexpected results. ° d ONLN d h tm *LThis is mainly due to the fact that the colorizing algorithm uses a pixel’s ° d ONLN dh hm t⁄ ( êãcolor table index value ° d ONLN dÄ t Ä ( ú 60rather than its actual RGB color. To illustrate ° d ONLN d∞ t Ä⁄ )˜&this, let’s assume that foreground and ° d ONLN d◊ Ä åy ( ® 6Fbackground colors are as above, and your image contains yellow with a ° d ONLN d Äy å⁄ ( ®ócolor table index of ° d ONLN d2 å ò  ( ¥ 6*1000. The colorizing operation would give: ,
Courier
° d ONLN d^ § < Øc +$;ColoredPixelValue = (NOT(1000) AND 0011) OR (1000 AND 1101) ° d ONLN dõ Æ < πc *
; 1011 = ( 0111 AND 0011) OR (1000 AND 1101)
° d ONLN d◊ ƒ –ï ( Ï 6NSince the color table may have any RGB color at the resulting index position, ° d ONLN d% ƒï –⁄ ( Ï≥the final color ° d ONLN d5 – ‹k ( ¯ 6Fmay not even be close to the source, foreground, or background colors. ° d ONLN d| Ë Ùé *PSimilar things occur if you are trying to colorize a black and white image when ° d ONLN dà Ëé Ù⁄ (¨white and black ° d ONLN d‹ Ù , ( 6>do not occupy the first and last positions in the color table. ° d ONLN d
ê *The bottom line rules for ° d ONLN d5 ê » )xCopyBits ° d ONLN d=
»s )8%ing in a color environment are these: ° d ONLN dc% *1 . (M H• ° d ONLN de% 71º )
OThou shalt set thy background color to white and thy foreground color to black ° d ONLN d¥%º1⁄ (M⁄before ° d ONLN dª2 7> Y (Z Ucalling ° d ONLN d√1 Y= ë )"CopyBits ° d ONLN dÀ2 ë> ° )8 or ° d ONLN dœ1 °= Ÿ )CopyMask ° d ONLN d◊2 Ÿ>ª )8., unless thou art coloring a monochrome image. ° d ONLN dJ *V . (r H• ° d ONLN dJ 7V∂ )
QThou shalt, when colorizing, make sure that the first color table entry is white ° d ONLN dYJ∂V⁄ (r‘and the ° d ONLN daV 7b J (~ Ulast ° d ONLN dgV `b ◊ ))color table entry is black. ° d ONLN dÉn z. (ñ 6<The second rule is easy to follow because the default color ° d ONLN døn.z⁄ (ñL$tables are constructed properly, and ° d ONLN d‰z Ü v (¢ 6if you are using the ° d ONLN d˘z vÜ⁄ )^KPalette Manager (and you are, right?) then it will make sure that the color ° d ONLN dEÜ í z (Æ 6tables obey this rule.
° d ONLN d\™ π Í *'How To Colorize—An Example
° d ONLN dw≈ — ò *This code fragment shows ° d ONLN dê≈ ò—⁄ )ÄDhow to implement a color fill, like the paint bucket in MacPaint. It ° d ONLN d’“ fi ü (˙ 6 relies on three main things: ° d ONLN dÚ— ü› fi )á SeedCFill ° d ONLN d˚“ fifih )? for calculating the fill area, ° d ONLN d—h›† )äCopyMask ° d ONLN d#“†fi∂ )8 for ° d ONLN d(“∂fi⁄ )actually ° d ONLN d1fi Í Ô ( 6,changing the bits, and QuickDraw colorizing.
° d ONLN d^ˆ : *:PROCEDURE PaintBucket(where: Point; paintColor: RGBColor); ° d ONLN dö
< K +$VAR ° d ONLN d† ` É +$
savedFG ° d ONLN d® ® fl )H : RGBColor; ° d ONLN d∂ `) É (E ~offBits ° d ONLN dæ ®) ’ )H : BitMap; ° d ONLN d…2 <= U (Y ZBEGIN ° d ONLN d—< `G +$
${First, create an offscreen bitmap.} ° d ONLN d¯F `Q *
%offBits.bounds := myWindow^.portRect; ° d ONLN d P `[ Ï *
WITH offBits.bounds DO BEGIN ° d ONLN d@Z Ñeç +$
5offBits.rowBytes := ((right - left + 15) DIV 16) * 2; ° d ONLN dyd Ño∞ *
<offBits.baseAddr := NewPtr((bottom-top) * offBits.rowBytes); ° d ONLN d∏n `y t (ï ~END; ° d ONLN døÇ `çZ *2{Check MemError here! Make sure NewPtr succeeded!} ¡ 4¡˘
(÷ 62 ) of 3 (÷n QD 4 - Colorizing With CopyBits +M.QD.ColorizingWithCopyBits ˇ ¨ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X / ,
Courier
° d ONLN d Ñ (ú ( D ¢8SeedCFill(myWindow^.portBits,offBits,myWindow^.portRect, ° d ONLN d < ' ® 2z +$
*myWindow^.portRect,where.h,where.v,NIL,0); ° d ONLN d i 1 Ñ < Ú ( X ¢GetForeColor(savedFG); ° d ONLN d Ç ; Ñ F *
RGBForeColor(paintColor); ° d ONLN d û E Ñ Pø *
?CopyMask(offBits,offBits,myWindow^.portBits,myWindow^.portRect, ° d ONLN d · O ® Zk +$
'myWindow^.portRect,myWindow^.portRect); ° d ONLN d Y Ñ d Ú ( Ä ¢RGBForeColor(savedFG); ° d ONLN d$ m Ñ x * DisposPtr(offBits.BaseAddr); ° d ONLN dB w ` Ç t ( û ~END;
° d ONLN dG é < ö É ( ∂ Z
The variable ° d ONLN dT ç É ô ¥ )GoffBits ° d ONLN d[ é ¥ ö )1 is an offscreen ° d ONLN dl ç ô= )_BitMap ° d ONLN dr é= öE )* ° d ONLN ds éE öo )(not a ° d ONLN dz ço ôô )*PixMap ° d ONLN dÄ éô öƒ )*) with ° d ONLN dá çƒ ôÓ )+bounds ° d ONLN dç éÓ ö˛ )* = ° d ONLN dê ö < ¶ ∫ ( √ ZmyWindow^.portRect ° d ONLN d¢ õ ∫ ß » )~. ° d ONLN d• ö » ¶ ) SeedCFill ° d ONLN dÆ õ ßy )? effectively creates, in ° d ONLN d« õy ßø )rthe offscreen ° d ONLN d’ öø ¶È )FBitMap ° d ONLN d€ õÈ ß˛ )*, a ° d ONLN d‡ ® < ¥_ ( – Z:monochrome image of the bits that we want to paint. Since ° d ONLN d ß_ ≥ê ( –}offBits ° d ONLN d! ®ê ¥Ì )1 contains the exact ° d ONLN d5 ®Ì ¥˛ )]bits ° d ONLN d: µ < ¡õ ( › ZLthat we want to paint, it is used as both the source image and the mask for ° d ONLN dÜ ¥õ ¿” ( ›πCopyMask ° d ONLN dé µ” ¡◊ )8. ° d ONLN dê Õ < Ÿ ( ı ZaBy setting the foreground color to the desired paint color, the result is a colorized version of ° d ONLN dÒ Õ Ÿ˛ ( ıthe ° d ONLN dı ⁄ < Ê • ( Zmask (the paint area) ° d ONLN d ⁄ • ÊJ )i being copied onto the window’s ° d ONLN d* ŸJ Ât )•PixMap ° d ONLN d0 ⁄t Ê˛ )* without affecting any other ° d ONLN dM Ê < Ú Q ( Zbits. ° d ONLN dS <" ¶ *0Further Reference: A XA ° d ONLN df# N/ R +
• ° d ONLN dh# `/ ¥ )Color QuickDraw ¡ X¡
(÷ Z QD 4 - Colorizing With CopyBits (÷3 ) of 3 (Ï ZM.QD.ColorizingWithCopyBits ˇ ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < Åh ( õ Z"QD 5 - Displaying Large PICT Files
° d ONLN d # Ä < è á * QuickDraw
° d ONLN d . õ < ß t * Revised by: ° d ONLN d ; õ≈ ߲ ( √„
March 1988 ° d ONLN d F ß < ≥ q ( œ Z Written by: ° d ONLN d R ß Ñ ≥ ∑ )H Rick Blair ° d ONLN d ^ ßœ ≥˛ ( œÌ July 1987 ° d ONLN d h ø < Àp ( Á Z>Now that we have scanners and other massive-picture producing ° d ONLN d ¶ øp À˛ ( Áé types of applications, there is ° d ONLN d Δ À < ◊ ( Û Z(a need to address the problem of how to ° d ONLN d Ó À ◊˛ )…2display a PICT format object that is bigger than a ° d ONLN d! ◊ < „k ( ˇ ZAcurrent PICT resource is allowed to be. Note that this technique ° d ONLN db ◊k „˛ ( ˇâ applies equally well to version ° d ONLN dÇ „ < Ôñ ( ZG1 and version 2 (word-opcode) pictures as produced by the Macintosh II. X
° d ONLN d <# » *4Future Compatibility
° d ONLN dfl0 << „ *"Think of the handle returned by a ,
Courier ° d ONLN d/ „;} )ßGetResource('PICT',ID) ° d ONLN d0}<≈ )ö as a “handle” ° d ONLN d&0≈<˛ )H in the more ° d ONLN d2< <H≥ (d ZMgeneral sense of being an abstract “tag”—something that the ROM routines can ° d ONLN d<≥H˛ (d—use to draw the ° d ONLN dèH <T¡ (p ZPpicture with. Don’t assume that the entire picture has been read into memory or ° d ONLN dflH¡T˛ (pfl that you can ° d ONLN dÏU <a (} Z)directly read any bytes beyond the basic ° d ONLN dT`3 )ΔPicture ° d ONLN d U3aç )1 record structure ( ° d ONLN d/Tç`æ )ZpicSize ° d ONLN d6Uæa˛ )1 followed by ° d ONLN dCa <m t (ä ZpicFrame ° d ONLN dKb tn° )8:). Someday we may provide a mechanism for the resource to ° d ONLN dÖb°n˛ (äøbe disk- instead of ° d ONLN dôn <zø (ñ ZLmemory-based. The QuickDraw bottleneck procedures will know how to get data ° d ONLN dÂnøz˛ (ñ› from and put ° d ONLN dÚz <Ü ÿ (¢ Z#data into the pictures in any case.
° d ONLN dû <≠ Ï *'Spooling from a PICT file
° d ONLN d0π <≈ **In order to display pictures of arbitrary ° d ONLN dZπ≈˛ )»1size, your application should be able to import a ° d ONLN då≈ <— ∫ (Ì ZQuickDraw picture from a ° d ONLN d•≈ ∫—˛ )~Afile of type PICT. This is the file produced by a “Save as…” from ° d ONLN dÁ— <› ˝ (˘ Z&MacDraw with the PICT option selected. ° d ONLN dÈ <ı} *?What follows is a small program fragment that demonstrates how ° d ONLN dMÈ}ı˛ (õto spool in a picture from ° d ONLN dhı < ~ ( Z[the data fork ° d ONLN dwı ~˛ )BQof] a PICT file. The picture can be larger than the historical 32K resource size. ° d ONLN d… <> (* Z6See technical note #88 if you are unfamiliar with the ° d ONLN dˇ>
h (*\Signal ° d ONLN dh˘ )* mechanism. We assume that ° d ONLN d ˘˛ )ëa ° d ONLN d" < ê (7 Z CatchSignals ° d ONLN d. ê ˙ )T has been done before ° d ONLN dD ˙x )jGetandDrawPICTFile
@ SFGetFile(wher,'',NIL,numFileTypes,myFileTypes,NIL,reply); ° d ONLN dï£ <Æ “ * IF reply.good THEN BEGIN ° d ONLN dµ≠ <∏Å *
A SetStdProcs(myProcs); {use SetStdCProcs for a CGrafPort} ° d ONLN d¯∑ <¬ *
, myProcs.getPicProc := @GetPICTData; ° d ONLN d&¡ <Ãö *
F savedProcs := thePort^.grafProcs; {set the grafProcs to ours} ° d ONLN dnÀ <÷ *
( thePort^.grafProcs := @myProcs; ° d ONLN dòfl <Ír *> myPicture := PicHandle(NewHandle(SizeOf(myPicture))); ° d ONLN dÿÛ <˛m *= Signal(FSOpen(reply.fname,reply.vRefNum,globalRef)); ° d ONLN d˝ <ã *
C Signal(GetEOF(globalRef,myEOF)); {get EOF for later check} ° d ONLN d\ <Ü *
B Signal(SetFPos(globalRef,fsFromStart,512)); {skip header} ° d ONLN d† <&h *< {read in the (obsolete) size word and the picFrame} ° d ONLN dfi% <0 *
( longCount := SizeOf(myPicture); ° d ONLN d/ <:m *
= Signal(FSRead(globalRef,longCount,Ptr(myPicture^))); ° d ONLN dGC <N§ *H DrawPicture(myPicture,myPicture^^.picFrame); {draw the picture} ° d ONLN dëW <bï *E Signal(GetFPos(globalRef,filePos)); {get position for check} ° d ONLN dÿa <l *
$ Signal(FSClose(globalRef)); ° d ONLN d˛u <Ä *) DisposHandle(Handle(myPicture)); ° d ONLN d)â <îr *> thePort^.grafProcs := savedProcs; {restore the procs} ¡ 4¡˘
(÷ 62 ) of 5 (÷d"QD 5 - Displaying Large PICT Files +%M.QD.DisplayingLargePict ˇ» ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1990 / X / ,
Courier
° d ONLN d ' ` 2} ( N ~9 {Check for errors. If there wasn't enough room,} ° d ONLN d ; 1 ` <} *
9 {DrawPicture will abort; the FILE position mark} ° d ONLN d v ; ` F7 *
+ {won't be at the end of the FILE.} ° d ONLN d £ E ` Pd *
4 IF filePos <> myEOF THEN Signal(abortPICT); ° d ONLN d Ÿ O ` Z ‚ *
END; {IF reply.good} ° d ONLN d ı Y ` d › *
END; {GetDrawPICTFile}
° d ONLN d { < ä ≠ ( ¶ Z
MPW C Example
° d ONLN d ñ < °@ *4/*replacement for the QuickDraw bottleneck routine*/ ° d ONLN dR † < ´ *
*pascal void GetPICTData(dataPtr,byteCount) ° d ONLN d} ™ < µ K *
Ptr ° d ONLN dÉ ™ ® µ – )ldataPtr; ° d ONLN dç ¥ < ø U ( € Zshort ° d ONLN dï ¥ ® ø ⁄ )l
byteCount; ° d ONLN d† “ < › õ ( ˘ Z{ /* GetPICTData */ ° d ONLN dµ ‹ ` Á y +$
OSErr ° d ONLN dΩ ‹ Ã Á ‡ )lerr; ° d ONLN d√ Ê ` Ò t (
~long ° d ONLN d Ê Ã Ò ˛ )l
longCount; ° d ONLN d÷ ˙ ` Œ (! ~longCount = byteCount; ° d ONLN dÓ `7 *
+err = FSRead(globalRef,&longCount,dataPtr); ° d ONLN d `Ø *
C/*can't check for an error because we don't know how to handle it*/ ° d ONLN d_ <# õ (? Z} /* GetPICTData */ ° d ONLN ds, <7 ı *%/*error code if DrawPicture aborted*/ ° d ONLN dô6 <A _ *
#define ° d ONLN d°6 ÑA Ë )H abortPICT 128 ° d ONLN døJ <U Ø (q ZOSErr GetDrawPICTFile() ° d ONLN dÿJ Uà )¥,/*read in a PICT FILE selected by the user*/ ° d ONLN d^ <i A (Ö Z{ ° d ONLN d^ `i … )$/* GetDrawPICTFile */ ° d ONLN d!r `} ~ *Point ° d ONLN d)r ®} Δ )Hwher; ° d ONLN d1r }w )H/*where to display dialog*/ ° d ONLN dN| `á É (£ ~SFReply ° d ONLN dV| ®á – )Hreply; ° d ONLN d_| á@ )H/*reply record*/ ° d ONLN dqÜ `ë í (≠ ~
numFileTypes; ° d ONLN d¿ö `• y (¡ ~OSErr ° d ONLN d«ö ®• º )Herr; ° d ONLN dÕ§ `Ø í (À ~
QDProcsPtr ° d ONLN dÿ§ ®Ø fl )H savedProcs; ° d ONLN dÂÆ `π É (’ ~QDProcs ° d ONLN dÌÆ ®π – )HmyProcs; ° d ONLN dˆÆ πü )H#/*use CQDProcs for a color window*/ ° d ONLN d∏ `√ ç (fl ~ PicHandle ° d ONLN d%∏ ®√ ⁄ )H
myPicture; ° d ONLN d0∏ √à )H,/*we need a picture handle for DrawPicture*/ ° d ONLN d^¬ `Õ t (È ~long ° d ONLN dd¬ ®Õ )HlongCount,myEOF,filePos; ° d ONLN d~÷ `· ∫ (˝ ~ wher.h = 20; ° d ONLN dí‡ `Î ∫ *
wher.v = 20; ° d ONLN d¶Í `ı ˆ *
numFileTypes = 1; ° d ONLN d«Í\ı )¸/*display PICT files*/ ° d ONLN dflÙ `ˇ ˆ ( ~ myFileTypes[0] = 'PICT'; ° d ONLN dˇ˛ ` • *
A SFGetFile(wher,'',nil,numFileTypes,myFileTypes,nil,&reply); ° d ONLN dB ` … * if (reply.good) ° d ONLN d\ Ñ' â +$
{ ° d ONLN da& ®1 +$
SetStdProcs(&myProcs); ° d ONLN d{0 ®;\ *
$/*use SetStdCProcs for a CGrafPort*/ ° d ONLN d°: `E ç (a ~ ° d ONLN d´: ®EM )H!myProcs.getPicProc = GetPICTData; ° d ONLN dŒD `O ç (k ~ ° d ONLN dÿD ®Oa )H%savedProcs = (*qd.thePort).grafProcs; ° d ONLN dX ®c9 * /*set the grafProcs to ours*/ ° d ONLN d b `m ç (â ~ ° d ONLN d*b ®mW )H#(*qd.thePort).grafProcs = &myProcs; ° d ONLN dOv `Å ç (ù ~ ° d ONLN dYv ®Å¢ )H2myPicture = (PicHandle)NewHandle(sizeof(Picture)); ¡ X¡
(÷ Z"QD 5 - Displaying Large PICT Files (÷3 ) of 5 (Ï ZM.QD.DisplayingLargePict ˇ@ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d Ñ (à +l4err = FSOpen(&reply.fName,reply.vRefNum,&globalRef); ° d ONLN d 8 ' Ñ 2 *
if (err != noErr) return err; ° d ONLN d W ; < F U ( b Z ° d ONLN d ] ; ` F e )$ ° d ONLN d _ ; Ñ F )$ err = GetEOF(globalRef,&myEOF); ° d ONLN d Ç E Ñ P *
/*get EOF for later check*/ ° d ONLN d ° O Ñ Z *
if (err != noErr) return err; ° d ONLN d ¬ c Ñ nú *8err = SetFPos(globalRef,fsFromStart,512);/*skip header*/ ° d ONLN d ¸ m < x i ( î Z ° d ONLN d m Ñ x )H if (err != noErr) return err; ° d ONLN d% Å < å i ( ® Z ° d ONLN d/ Å Ñ åç )H5/*read in the (obsolete) size word and the picFrame*/ ° d ONLN df ã < ñ i ( ≤ Z ° d ONLN dp ã Ñ ñ )H longCount = sizeof(Picture); ° d ONLN dé ï < † d ( º Z ° d ONLN dó ï Ñ †à )H4 err = FSRead(globalRef,&longCount,(Ptr)*myPicture); ° d ONLN dÕ ü < ™ i ( Δ Z ° d ONLN d◊ ü Ñ ™ )H if (err != noErr) return err; ° d ONLN dˆ ≥ < æ i ( ⁄ Z ° d ONLN d ≥ Ñ æó )H7DrawPicture(myPicture,&(**myPicture).picFrame); /*draw ° d ONLN d? Ω »U +ê
the picture*/ ° d ONLN dP — Ñ ‹ç ( ¯ ¢5err = GetFPos(globalRef,&filePos);/*get position for ° d ONLN dç € Ê7 +ê
check*/ ° d ONLN dñ Â < i ( Z ° d ONLN d† Â Ñ )H if (err != noErr) return err; ° d ONLN dø Ô < ˙ i ( Z ° d ONLN d… Ô Ñ ˙ )Herr = FSClose(globalRef); ° d ONLN d‰ ˘ < i ( Z ° d ONLN dÓ ˘ Ñ )H if (err != noErr) return err; ° d ONLN d
< i (4 Z ° d ONLN d
Ñ$ )H DisposHandle((Handle)myPicture); ° d ONLN d9! <, i (H Z ° d ONLN dC! Ñ,É )H3(*qd.thePort).grafProcs = savedProcs;/*restore the ° d ONLN d~+67 +ê
procs*/ ° d ONLN dá? <J d (f Z ° d ONLN dê? ÑJÉ )H3 /*Check for errors. if there wasn't enough room,*/ ° d ONLN d≈I <T d (p Z ° d ONLN dŒI ÑTÉ )H3 /*DrawPicture will abort; the FILE position mark*/ ° d ONLN dS <^ i (z Z ° d ONLN d
S Ñ^8 )H$/*won't be at the end of the FILE.*/ ° d ONLN d5g ÑrL *(if (filePos != myEOF) return abortPICT; ° d ONLN daq Ñ| fi *
else return noErr; ° d ONLN du{ <Ü » (¢ Z } /*if (reply.good) */ ° d ONLN díÖ ê " (¨ 6} ° d ONLN dïÖ <ê • )$/* GetDrawPICTFile */
° d ONLN d´ß ∂ Â (“ 6 More on Picture Compatibility
° d ONLN d…¬ Œ ô *Many applications already ° d ONLN d„¬ ôŒ⁄ )Å:support PICT resources larger than 32K. The 128K ROMs (and ° d ONLN d Œ ⁄ ‰ (ˆ 6)later) allow pictures as large as memory ° d ONLN dGŒ ‰⁄⁄ )Ã-(or spooling) will accommodate. This was made ° d ONLN du⁄ Ê Œ ( 6$possible by having QuickDraw ignore ° d ONLN dô⁄ ŒÊ÷ )∂7the size word and simply read the picture until the end ° d ONLN d–⁄÷Ê⁄ (Ù- ° d ONLN d—Ê Ú ¨ ( 6 of-picture opcode was reached. ° d ONLN d˛
√ *WFor maximum safety and convenience, let QuickDraw generate and interpret your pictures. ° d ONLN dH "á *MWhile Apple has provided you with the data formats that allow you to read or ° d ONLN dïá"⁄ (>•write picture data ° d ONLN d®" . ˆ (J 6+directly, we recommend that you always let ° d ONLN d”" ˆ.⁄ )fi+DrawPicture or OpenPicture and ClosePicture ° d ONLN dˇ. : { (V 6process the opcodes. ° d ONLN dF Rª *YOne reason to read a picture directly by scanning the opcodes would be to disassemble it ° d ONLN dmFªR⁄ (nŸto, for ° d ONLN duR ^ s (z 6example, extract a ° d ONLN dàR s^⁄ )[GColor QuickDraw pixel map to save off in a private data structure. This ° d ONLN d–^ j µ (Ü 6 shouldn’t normally be necessary. ° d ONLN dÒv Ç ¬ *&If you do look at the picture data be ° d ONLN dv ¬Ç⁄ )™7sure and check the version information. You may want to ° d ONLN dOÇ é ˘ (™ 63put up an alert in your application that indicates ° d ONLN dÇÇ ˘é⁄ )·.to the user when a picture was created using a ¡ 4¡˘
(÷ 64 ) of 5 (÷d"QD 5 - Displaying Large PICT Files +%M.QD.DisplayingLargePict ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1990 / X /
° d ONLN d < )Ì ( E ZXlater version of the picture format than your application recognizes, letting them know ° d ONLN d X Ì )˛ ( E that ° d ONLN d ] ) < 5… ( Q ZMsome elements of the picture cannot be displayed. If the version information ° d ONLN d ™ )… 5˛ ( QÁ indicates a ° d ONLN d ∂ 5 < A Ÿ ( ] Z QuickDraw picture version later ° d ONLN d ÷ 5 Ÿ A˛ )ù9than the one recognized by your application, your program ° d ONLN d A < M∞ ( i ZMshould skip over the new opcodes and only attempt to parse the ones it knows. ° d ONLN d^ Y < e- *5As with reading picture data directly, it is best to ° d ONLN dì Y- e˛ )Ò(use QuickDraw to create data in the PICT ° d ONLN dº e < qS ( ç Z<format. If you do need to create PICT format data directly, ° d ONLN d¯ eS q˛ ( çq'it is essential that you use the latest ° d ONLN d q < } ( ô ZWopcode specifications and that you thoroughly test the data produced on both color and ° d ONLN dw q }˛ ( ôblack ° d ONLN d} } < âí ( • ZDand white Macintosh machines. Contact Macintosh Developer Technical ° d ONLN d¡ }í Ⲡ( •∞Support if you are not ° d ONLN dÿ â < ï ( ± Z-sure that you have the latest specifications. ° d ONLN d ° < ≠· *UApple does not guarantee that a picture which wasn’t produced by QuickDraw will work. ° d ONLN d\ — < › ¶ *0Further Reference: ¸ X ¸ ° d ONLN do fi N Í R +
• ° d ONLN dq fi ` Í ñ ) QuickDraw ° d ONLN d{ Í N ˆ R ( l• ° d ONLN d} Í ` ˆ# )$Technical Note M.IM.PictureOpcodes — ° d ONLN d§ ˆ Ñ Ò +$ Internal Picture Format ° d ONLN dº N R (* l• ° d ONLN dæ ` ¸ ) Technical Note M.PT.Signals — ° d ONLN dfi Ñ ß +$ Signals ¡ X¡
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < Å x ( õ ZQD 6 ° d ONLN d n x Å˛ )<*- Every Picture [Comment] Tells Its Story, ° d ONLN d 0 Ä < ì á ( ≠ Z Don’t It?
° d ONLN d : í < ° á * QuickDraw
° d ONLN d E ≠ < π t * Revised by: ° d ONLN d R ≠¬ π˛ ( ’‡ March 1988 ° d ONLN d ^ π < ≈ q ( · Z Written by: ° d ONLN d j π Ñ ≈ ¥ )H
Rick Blair ° d ONLN d u π± ≈˛ ( ·œ
November 1987 ° d ONLN d É — < › » ( ˘ Z Application-specific picture ° d ONLN d † — » ›˛ )å:comment conflict and registration is addressed, along with ° d ONLN d € › < È8 ( Z4Developer Technical Support’s method for solving it. X ° d ONLN d < ◊ *%"I will assume that the nature and ° d ONLN d2 ◊˛ )õ:usefulness of picture comments are already well known. The ° d ONLN dm < ‰ (6 Z$problem I am addressing is that, as ° d ONLN dë ‰˛ )®:it stands, developers must register their comments with us ° d ONLN dà <&π (B ZL(Developer Technical Support) or run the risk of using the same comments as ° d ONLN dπ&˛ (B◊
those used by ° d ONLN d&& <2 (N Z,Apple or within another third party product. ° d ONLN dS> <JD *2The idea here is to provide a “metacomment” which ° d ONLN dÖ>DJ˛ (fb$will contain information about which ° d ONLN d™J <VX (r Z;application owns the comment as well as the comment itself: ,
Courier
° d ONLN dÊb <m · *!ApplicationComment (long comment) ° d ONLN db mh )¥kind = 100 size = n + 6 ° d ONLN d"l `w• (ì ~Adata = application signature (i.e. 'MPNT' for MacPaint) = 4 bytes ° d ONLN dev `Å- *
) application “local” kind = 2 bytes ° d ONLN dêÄ `ã Ò *
comment data = n bytes
° d ONLN dÆñ <¢ ◊ (æ Z In this way each comment may ° d ONLN dÀñ ◊¢˛ )õ?be specific to an application. It is still up to a developer to ° d ONLN d ¢ <Æ- ( Z1publish information about the comments they have ° d ONLN d<¢-Æ˛ )Ò*defined if they wish them to be understood ° d ONLN dgÆ <∫ ƒ (÷ Zand used by other programs. ° d ONLN dÉΔ <“É *FPreviously assigned and registered comments will still be valid. This ° d ONLN d…ΔÉ“˛ (Ó°means that those defined ° d ONLN d„“ <fi≥ (˙ ZOfor the LaserWriter or MacDraw, for instance, will retain their normal meaning. ° d ONLN d3Í <ˆ Ë *$Suppose your application (creator =
° d ONLN dWÍ Ëˆ )¨'MYAP')
° d ONLN d^͈˛ )*. wanted to define a comment. The appearance of ° d ONLN dçˆ < N ( Zthe ° d ONLN dëˆ N˛ )Rcomment would be as follows (assuming you chose 128 to be the “local” kind for the ° d ONLN d‰ < n (* Z comment):
° d ONLN dÔ `%π +$Ekind = 100; data = 'MYAP' [4 bytes] + 128 [2 bytes] + additional data
° d ONLN d5H <T ¶ (p ZFurther Reference: s Xs ° d ONLN dHU Na R +
• ° d ONLN dJU `a ñ ) QuickDraw ° d ONLN dTa Nm R (â l• ° d ONLN dVa `m )"Technical Note M.IM.PictComments — ° d ONLN d|m Ñyx +$ /Optimizing for the LaserWriter—Picture Comments ¡ X¡
(÷ Z9QD 6 - Every Picture [Comment] Tells Its Story, Don’t It? (÷1 ) of 1 (Ï ZM.QD.EveryPictureComment ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø™ ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. eRSeRS +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d o < Ç ( ú ZQD 7 - Off-Screen Bitmaps
° d ONLN d Å < ê á * QuickDraw
° d ONLN d % ú < ® t * Revised by: ° d ONLN d 1 ú Ñ ® )HJon Zap & Forrest Tanaka ° d ONLN d J úÕ ®˛ ( ƒÎ June 1990 ° d ONLN d T ® < ¥ q ( – Z Written by: ° d ONLN d ` ® Ñ ¥) )H!Jim Friedlander & Ginger Jernigan ° d ONLN d Ç ®œ ¥˛ ( –Ì July 1985 ° d ONLN d å ¿ < à û ( Ë ZThis Technical Note ° d ONLN d † ¿ û Ã˛ )bHprovides an example of creating an off-screen bitmap, drawing to it, and ° d ONLN d È Ã < ÿ fi ( Ù Z#then copying from it to the screen. ° d ONLN d
ÿ < ‰ ÿ * Changes since April 1990: ° d ONLN d& ÿ ÿ ‰# )ú Clarified the ° d ONLN d6 ÿ# ‰˛ )K)section on window updates with off-screen ° d ONLN d` ‰ < e ( Z>bitmaps to explicitly limit these updates to your own windows. X ° d ONLN dü < *%(The following is an example of creating ° d ONLN d« ˛ )≈1and drawing to an off-screen bitmap, then copying ° d ONLN d˘ <!” (= ZQfrom it to an on-screen window. We supply this example in both MPW Pascal and C. ° d ONLN dK- <9 É *
MPW Pascal ° d ONLN dVE <Q *'First, let’s look at a general purpose ° d ONLN d}E Q˛ )¥7function to create an off-screen bitmap. This function ° d ONLN dµR <^ t (z Z creates the ,
Courier ° d ONLN d¡Q t] ¨ )8GrafPort ° d ONLN d…R ¨^ Ù )8 on the heap. ° d ONLN d◊R Ù^˛ )H3 You could also create it on the stack and pass the ° d ONLN d ^ <j: (Ü Z:uninitialized structure to a function similar to this one.
° d ONLN dFv <Å÷ *RFUNCTION CreateOffscreenBitMap(VAR newOffscreen:GrafPtr; inBounds:Rect) : BOOLEAN; ° d ONLN dôä <ï K *VAR ° d ONLN dùî <ü ™ *
newPort : GrafPtr; ° d ONLN dÀ≤ <Ω U *BEGIN ° d ONLN d—º <«‡ *
T GetPort(savePort); {need this to restore thePort after OpenPort changes it} ° d ONLN d&– <€Æ *J newPort := GrafPtr(NewPtr(sizeof(GrafPort))); {allocate the GrafPort} ° d ONLN dq⁄ < · *
! IF MemError <> noErr THEN BEGIN ° d ONLN dì‰ <ÔÆ *
J CreateOffscreenBitMap := false; {failed to allocate it} ° d ONLN dfiÓ <˘ ‹ *
EXIT(CreateOffscreenBitMap); ° d ONLN dˇ¯ < Z *
END; ° d ONLN d <
K *
{ ° d ONLN d
< *
, the OpenPort call does the following . . . ° d ONLN d8 <!« *
O allocates space for visRgn (set to screenBits.bounds) and clipRgn (set wide ° d ONLN dâ <+ i *
open) ° d ONLN dì* <5 ◊ *
sets portBits to screenBits ° d ONLN d≥4 <? ˙ *
& sets portRect to screenBits.bounds ° d ONLN d⁄> <I √ *
etc. (see IM I-163,164) ° d ONLN dˆH <S *
* side effect: does a SetPort(offScreen) ° d ONLN d!R <] K *
} ° d ONLN d%\ <g † *
OpenPort(newPort); ° d ONLN d:f <qã *
C {make bitmap exactly the size of the bounds that caller supplied} ° d ONLN d~p <{ü *
G WITH newPort^ DO BEGIN {portRect, clipRgn, and visRgn are in newPort} ° d ONLN dΔz <Ö π *
portRect := inBounds; ° d ONLN d‡Ñ <è∏ *
L RectRgn(clipRgn, inBounds); {avoid wide-open clipRgn, to be safe} ¡ X¡
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø¶ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d (î *L RectRgn(visRgn, inBounds); {in case inBounds is > screen bounds} ° d ONLN d M ' 2 6 *
END; ° d ONLN d T ; Fô *M WITH newPort^.portBits DO BEGIN {baseAddr, rowBytes and bounds are in ° d ONLN d ¢ E P J *
newPort} ° d ONLN d ≠ O Z ã *
bounds := inBounds; ° d ONLN d ≈ Y dî *
L {rowBytes is size of row It must be rounded up to even number of bytes} ° d ONLN d c ng *
C rowBytes := ((inBounds.right - inBounds.left + 15) DIV 16) * 2; ° d ONLN dV w ÇD *< {number of bytes in BitMap is rowBytes * number of rows} ° d ONLN dì Å å≤ *
R {see note at end of Technical Note about using _NewHandle rather than _NewPtr} ° d ONLN dÊ ã ñè *
K baseAddr := NewPtr(rowBytes * LONGINT(inBounds.bottom - inBounds.top)); ° d ONLN d2 ï † 6 *
° d ONLN dF7 C∏ *ZHere is the procedure to get rid of an off-screen bitmap created by the previous function:
° d ONLN d°O Z5 *9PROCEDURE DestroyOffscreenBitMap(oldOffscreen : GrafPtr); ° d ONLN d€Y d 1 *
BEGIN ° d ONLN d·c n® *
P ClosePort(oldOffscreen); { dump the visRgn and clipRgn } ° d ONLN d2m xb *
B DisposPtr(oldOffscreen^.portBits.baseAddr); { dump the bits } ° d ONLN duw Çb *
B DisposPtr(Ptr(oldOffscreen)); { dump the port } ° d ONLN d∏Å å , *
END;
° d ONLN dΩó £è *HNow that you know how to create and destroy an off-screen bitmap, let’s ° d ONLN dóè£⁄ (ø≠go through the ° d ONLN d§ ∞^ (à 6Dmotions of using one. First, let’s define a few things to make the ° d ONLN dX£^ا (Ã|
_NewWindow ° d ONLN db§§∞º )F call ° d ONLN dh§º∞⁄ )a little ° d ONLN dq∞ º ; (ÿ 6clearer.
. +Z-Developer Support Center ( -Û June 1990 / X / ,
Courier
° d ONLN d < (Ü ( D ZB myWindow := NewWindow(NIL, myWBounds, 'Test Window', kIsVisible, ° d ONLN d C ' < 2÷ *
R noGrowDocProc, WindowPtr(kMakeFrontWindow), kNoGoAway, 0); ° d ONLN d ñ ; < Fü *G IF NOT CreateOffscreenBitMap(offscreen,myWindow^.portRect) THEN BEGIN ° d ONLN d fl E < P á *
SysBeep(1); ° d ONLN d Ô O < Z å *
ExitToShell; ° d ONLN d Y < d Z *
END; ° d ONLN d m < x" *. { Example drawing to our off-screen bitmap } ° d ONLN d6 w < Ç • *
SetPort(offscreen); ° d ONLN dL Å < åà *
P OSRect := offscreen^.portRect; { offscreen bitmap's local coordinate rect } ° d ONLN dù ã < ñ • *
L MoveTo((left+right-StringWidth(myString)) DIV 2, (top+bottom-12) DIV 2); ° d ONLN d¶ € < Ê õ *
TextMode(srcXor); ° d ONLN d∫ Â < Ø *
DrawString(myString); ° d ONLN d“ ˘ <« *O { copy from the off-screen bitmap to the on-screen window. Note that in this ° d ONLN d" <∏ *
L case the source and destination rects are the same size and both cover the ° d ONLN do
<≥ *
K entire area. These rects are allowed to be portions of the source and/or ° d ONLN dª <"— *
Q destination and do not have to be the same size. If they are not the same size ° d ONLN d
! <, *
- then _CopyBits scales the image accordingly ° d ONLN d;+ <6 K *
} ° d ONLN d?5 <@ † *
SetPort(myWindow); ° d ONLN dT? <J; *
3 CopyBits(offscreen^.portBits, myWindow^.portBits, ° d ONLN dàI <TÜ *
B offscreen^.portRect, myWindow^.portRect, srcCopy, NIL); ° d ONLN dÀ] <hm *= DestroyOffscreenBitMap(offscreen); {remove the evidence} ° d ONLN d q <|« *O WHILE NOT Button DO; {give user a chance to see the results} ° d ONLN dY{ <Ü P *
? /* make bitmap the size of the bounds that caller supplied */ ° d ONLN d Z ; F ∏ *
newPort->portRect = *inBounds; ° d ONLN d { E P € *
' newPort->portBits.bounds = *inBounds; ° d ONLN d £ O Zº *
T RectRgn(newPort->clipRgn, inBounds); /* avoid wide-open clipRgn, to be safe */ ° d ONLN d ¯ Y dº *
T RectRgn(newPort->visRgn, inBounds); /* in case newBounds is > screen bounds */ ° d ONLN dM m x≠ *Q /* rowBytes is size of row, it must be rounded up to an even number of bytes */ ° d ONLN dü w Ç∑ *
S newPort->portBits.rowBytes = ((inBounds->right - inBounds->left + 15) >> 4) << 1; ° d ONLN dÛ ã ñN *> /* number of bytes in BitMap is rowBytes * number of rows */ ° d ONLN d2 ï †≤ *
R /* see notes at end of Technical Note about using _NewHandle rather than _NewPtr ° d ONLN dÖ ü ™ ; *
S NewPtr(newPort->portBits.rowBytes * (long) (inBounds->bottom - inBounds- ° d ONLN d Ω » r *
>top)); ° d ONLN d « “≤ *
R if (MemError()!=noErr) { /* check to see if we had enough room for the bits */ ° d ONLN df — ‹ Ü *
SetPort(savePort); ° d ONLN d} € ÊN *
> ClosePort(newPort); /* dump the visRgn and clipRgn */ ° d ONLN dº Â *
4 DisposPtr((Ptr)newPort); /* dump the GrafPort */ ° d ONLN dÒ Ô ˙0 *
8 return false; /* tell caller we failed */ ° d ONLN d* ˘ 1 *
} ° d ONLN d0 Ä *
H /* since the bits are just memory, let's clear them before we start */ ° d ONLN dy
ô *
M EraseRect(inBounds); /* OpenPort did a SetPort(newPort) so we are ok */ ° d ONLN d« " ö *
*newOffscreen = newPort; ° d ONLN d‚! , | *
SetPort(savePort); ° d ONLN d˜+ 6D *
< return true; /* tell caller we succeeded! */ ° d ONLN d45 @ *
}
° d ONLN d6K W∞ *YHere is the function to get rid of an off-screen bitmap created by the previous function:
° d ONLN dêc n
*1void DestroyOffscreenBitMap(GrafPtr oldOffscreen) ° d ONLN d¬m x *
{ ° d ONLN dƒw Ç≤ *
R ClosePort(oldOffscreen); /* dump the visRgn and clipRgn */ ° d ONLN dÅ ål *
D DisposPtr(oldOffscreen->portBits.baseAddr); /* dump the bits */ ° d ONLN d\ã ñl *
D DisposPtr((Ptr)oldOffscreen); /* dump the port */ ° d ONLN d°ï † *
}
° d ONLN d£´ ∑è *HNow that you know how to create and destroy an off-screen bitmap, let’s ° d ONLN dδè∑⁄ (”≠go through the ° d ONLN d˙∏ ƒ^ (‡ 6Dmotions of using one. First, let’s define a few things to make the ° d ONLN d>∑^√§ (‡|
_NewWindow ° d ONLN dH∏§ƒº )F call ° d ONLN dN∏ºƒ⁄ )a little ° d ONLN dWƒ – ; (Ï 6clearer.
° d ONLN d`‹ Á ã *#define kIsVisible true ° d ONLN dxÊ Ò ã *
#define kNoGoAway false ° d ONLN dê ˚ ü *
#define kNoWindowStorage 0L ° d ONLN d¨˙ ÷ *
&#define kFrontWindow ((WindowPtr) -1L)
° d ONLN d” ± *!Here’s the body of the test code:
° d ONLN dı( 3 6 *main() ° d ONLN d¸2 = *
{ ° d ONLN d˛< G0 *
8 char* myString = "\pThe EYE"; /* string to display */ ° d ONLN d7P [D *< GrafPtr offscreen; /* our off-screen bitmap */ ° d ONLN dtZ eS *
? Rect ovalRect; /* used for example drawing */ ° d ONLN d¥d o: *
: Rect myWBounds; /* for creating window */ ° d ONLN dÔn y£ *
O Rect OSRect; /* portRect and bounds for off-screen bitmap*/ ° d ONLN d ?x É Å *
_NewHandle ° d ONLN dê Ç• )F6 so the Memory Manager can move them when necessary. ° d ONLN dΔ•˛ (+√To implement this ° d ONLN dÿ < ¢ (8 Zapproach, you need ° d ONLN dÎ ¢ c )f%to keep the handle separate from the ° d ONLN d cõ )¡GrafPort ° d ONLN d õ ˛ )8 (for example, in a ° d ONLN d , <) | (E Zstructure that ° d ONLN d ; |) ∂ )@ combines a ° d ONLN d F ∂( Ó ):GrafPort ° d ONLN d N Ó) )8 and a ° d ONLN d U (: )"Handle ° d ONLN d [ :)˛ )*'). When you want to use the off-screen ° d ONLN d É* <67 (R Z2bitmap you would then lock the handle and put the ° d ONLN d µ*76Δ )˚ dereferenced handle into the ° d ONLN d “)Δ5˛ )èbaseAddr ° d ONLN d €6 <B¢ (^ ZLfield. When you are not using the off-screen bitmap you can then unlock it. ° d ONLN d
(N <Z Â *"This example does not demonstrate ° d ONLN d
äZ Wf˛ )Opreserve the contents of windows so that after a temporary window or dialog box ° d ONLN d
⁄f <r ˘ (é Z%obscures part of your windows and is ° d ONLN d
ˇf ˘r˛ )Ω4then dismissed, you can quickly handle the resulting ° d ONLN d 4r <~† (ö ZJupdate events without recreating all of the intermediate drawing commands. ¡ X¡
° d ONLN d )V *DMake sure you only restore the pixels within the content regions of ° d ONLN d D V )⁄ ( Etyour own windows in case ° d ONLN d ] ) 5 € ( Q 6%the temporary window partly obscures ° d ONLN d Ç ) € 5⁄ )√1windows belonging to other applications or to the ° d ONLN d ¥ 5 A √ ( ] 6$desktop. Another application could ° d ONLN d ÿ 5 √ A⁄ )´8change the contents of its windows while they are behind ° d ONLN d A MP ( i 6<your temporary window, so you cannot simply restore all the ° d ONLN dM AP M⁄ ( inpixels that were behind the ° d ONLN di M Y M ( u 6
temporary ° d ONLN ds M M Y⁄ )5Mwindow because that would restore the old contents of the other application’s ° d ONLN d¡ Y e w ( Å 6windows. Instead, ° d ONLN d‘ Y w e⁄ )_Eyou could keep keep an off-screen bitmap for each of your windows and ° d ONLN d e q R ( ç 6
then restore ° d ONLN d' e R q⁄ ):Lthem by copying each bit map into the corresponding window’s ports when they ° d ONLN dt q } Ö ( ô 6get their update events. ° d ONLN dç â ï | *An alternate method ° d ONLN d° â | ï⁄ )dGis to make a single off-screen bitmap that is as large as the temporary ° d ONLN dÈ ï °û ( Ω 6Nwindow and a region that is the union of the content regions of your windows. ° d ONLN d7 ïû °⁄ ( Ωº Before you ° d ONLN dC ° ≠ ( … 63display the temporary window, copy the screen into ° d ONLN dv ° ≠⁄ )¯*the off-screen bit map using the region as ° d ONLN d° ≠ π
( ’ 62a mask. After the temporary window is dismissed, ° d ONLN d” ≠
π⁄ )ı)restore the obscured area by copying from ° d ONLN d˝ π ≈I ( · 6?the off-screen bit map into a copy of the Window Manager port, ° d ONLN d< πI ≈⁄ ( ·g and use the region as a mask. ° d ONLN d[ Δ “ ˘ ( Ó 61If the region has the proper shape and location, ° d ONLN då Δ ˘ “/ )· it prevents ,
Courier ° d ONLN dò ≈/ —n )6 _CopyBits ° d ONLN d° Δn “⁄ )? from drawing outside ° d ONLN d∑ “ fi Ì ( ˙ 6)of the content regions of your windows. ° d ONLN d‡ “ Ì fi⁄ )’,See Technical Note #194, WMgrPortability for ° d ONLN d
You may also ° d ONLN d Yü \´⁄ )DKwant to refer to the OffScreen library (DTS Sample Code #15) which provides ° d ONLN d •´ ∑ P (” 6 both high- ° d ONLN d ∞´ P∑⁄ )8Iand low-level off-screen bitmap support for the 128K and later ROMs. The ° d ONLN d ˙∑ √• (fl 6QOffSample application (DTS Sample Code #16) demonstrates the use of this library. ° d ONLN d
LÁ Û Ç *0Further Reference: 4˘ ° d ONLN d
_Ù * . +
• ° d ONLN d
aÙ < ç )Inside Macintosh ° d ONLN d
qÙ ç )Q, Volumes I & IV, QuickDraw ° d ONLN d
ç * . (( H• ° d ONLN d
è < ç )Inside Macintosh ° d ONLN d
ü ç )Q, Volume V, Color QuickDraw ° d ONLN d
ª * . (4 H• ° d ONLN d
Ω <
)(Technical Note M.IM.PrincipiaOffscreen — ° d ONLN d
Ë `$4 +$ *Principia Off-Screen Graphics Environments ° d ONLN d $ *0 . (L H• ° d ONLN d $ <0 È ) Technical Note M.TB.WMgrPort — ° d ONLN d 60 `< ≥ +$ WMgrPortability ° d ONLN d G< *H . (d H• ° d ONLN d I< <Ho )9DTS Macintosh Sample Code #15, OffScreen & #16, OffSample ¡ 4¡˘
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < Å ( õ ZQD 8 - Old-Style Colors
° d ONLN d Ä < è á * QuickDraw
° d ONLN d # õ < ß t * Revised by: ° d ONLN d / õ Ñ ß À )H
Bill Guschwan ° d ONLN d = õŒ ߲ ( √ÏMay 1993 ° d ONLN d F ß < ≥ q ( œ Z Written by: ° d ONLN d R ß Ñ ≥T )H)Rich “I See Colors” Collyer and Byron Han ° d ONLN d | ßæ ≥˛ ( œ‹ October 1989 ° d ONLN d â ø < À Ù ( Á Z'This Technical Note covers limitations ° d ONLN d ∞ ø Ù À˛ )∏8of the original Macintosh color model (eight-color) that ° d ONLN d È À < ◊ ç ( Û ZInside Macintosh ° d ONLN d ˘ À ç ◊ó )Q4 Volume I, page I-173, QuickDraw, does not document. ° d ONLN d. „ < Ô · ( ZChanges since October 1989: ° d ONLN dK Ô < ˚
* -Added definitions of the old-style constants. ° d ONLN dy ˚ <ô * KCorrected definitions of old-style constants to reflect MPW 3.2 interfaces. 2 X2 ° d ONLN dΔ <,Ê *%QQuickDraw has always been able to deal with color, just on a very limited basis. ° d ONLN d Ê,˛ (HMost ° d ONLN d , <8Õ (T ZLapplications have not made use of this feature, since Color QuickDraw–based ° d ONLN dh,Õ8˛ (TÎ Macintosh ° d ONLN dr8 <D ¨ (` Zcomputers come with a ° d ONLN dà8 ¨D˛ )pEbetter color model. There are, however, a few nice features that come ° d ONLN dŒD <P ó (l Zwith the old-style ° d ONLN d·D óP˛ )[Gcolor model. With the old-style colors, it is easy to print color on an ° d ONLN d)P <\= (x Z3ImageWriter with a color ribbon. Another advantage ° d ONLN d\P=\˛ (x['is that developers do not have to write ° d ONLN dÑ\ <h∏ (Ñ ZLspecial-case code depending on whether or not a machine has Color QuickDraw. ° d ONLN d—t <Äé *GNow that you are ready to convert to the old-style colors, there are a ° d ONLN dtéIJ (ú¨few things you should ° d ONLN d.Ä <å Z (® Zknow ° d ONLN d3Ä Zå˛ ) Wabout that do not work with old-style colors. This Note covers the limitations of using ° d ONLN dãå <òú (¥ ZLold-style colors, as well as the best ways to work around these limitations.
° d ONLN dÿ∞ <ø à *' Limitations
° d ONLN d‰À <◊ k * The most ° d ONLN dÌÀ k◊˛ )/Vobvious limitation is that of only eight colors: black, white, red, green, blue, cyan, ° d ONLN dD◊ <„Ø (ˇ ZNyellow, and magenta. This limitation is a problem only if you want to produce ° d ONLN dí◊Ø„˛ (ˇÕa color-intensive ° d ONLN d§„ <Ôı ( Zaapplication; if this describes your application, then you need not read any further in this Note. ° d ONLN d˚ < *3The next limitation is that off-screen buffers are ° d ONLN d9˚ ˛ )„-not very useful. You can draw into off-screen ° d ONLN dg <4 (/ Z4buffers, but there is no way to get the colors back ° d ONLN dõ4˛ )¯)from the buffer. This leads into the next ° d ONLN d≈ < Æ (< Zlimitation, which is that ,
Courier ° d ONLN dfl Æ Ì )r _CopyBits ° d ONLN dË Ì ∏ )?+ cannot copy more than one color at a time. ° d ONLN d- <9 Ü (U ZWhen you call ° d ONLN d", Ü8 ≈ )J _CopyBits ° d ONLN d+- ≈9û )?+ from an off-screen buffer to your window, ° d ONLN dV-û9˛ )Ÿyou need to set the ° d ONLN dj: <F: (b Z7forecolor to the color you want to copy before calling ° d ONLN d°9:Ey )˛ _CopyBits ° d ONLN d™:yFÀ )? (for example, to ° d ONLN dº:ÀF˛ )R
copy a red ° d ONLN d«G <S r (o Z
object, call ° d ONLN d‘F rR ˛ )6_ForeColor(redColor) ° d ONLN dËG ˛S§ )å!). Now when you copy the object, ° d ONLN d G§S˛ )¶you can copy only ° d ONLN dS <_ ({ Z)one color. If you copy different colored ° d ONLN dDS_˛ )≈1objects at one time, then you have a problem. The ° d ONLN dv_ <kÛ (á Zaresult of a multicolored copy is that all objects copy in the same color, that of the foreground. ¡ X¡
° d ONLN df q | Å * SetPort (myPort); ° d ONLN d| { Ü ≥ *
savedFG := myPort^.fgColor; ° d ONLN dú Ö ê5 *
9 ForeColor (redColor); {or any other color} ° d ONLN d÷ ô § Ã *$ {...drawing takes place here...} ° d ONLN d˚ ≠ ∏ ê * ForeColor (savedFG);
° d ONLN d ƒ – Û *-Surprise. It does not always work. The saved ° d ONLN dA ƒ Û –4 )€value for the ° d ONLN dO √4 œe )AfgColor ° d ONLN dV ƒe –¢ )1 field of the ° d ONLN dd √¢ œ⁄ )=grafPort ° d ONLN dm — › Œ ( ˘ 6(is not a classic QuickDraw color if the ° d ONLN dï – Œ ‹ )∂grafPort ° d ONLN dù — ›C )8 is actually a ° d ONLN d¨ –C ‹Ç )= cGrafPort ° d ONLN dµ —Ç ›⁄ )?. If dealing with a ° d ONLN d… › È W ( 6 cGrafPort ° d ONLN d“ fi W Í q )?, the ° d ONLN dÿ › q È ¢ )fgColor ° d ONLN dfl fi ¢ Í$ )1 field actually contains the ° d ONLN d¸ fi$ Í⁄ )Ç%foreground color’s entry in the color ° d ONLN d" Î ˜ ó ( 6 table, so the second call to ° d ONLN d? Í ó ˆ › )
_ForeColor ° d ONLN dI Î › ˜R )F really messes things up. ° d ONLN dc ¿ (, 6$The proper way to set and reset the ° d ONLN dá ¿î )®*foreground color with classic QuickDraw’s ° d ONLN d±î⁄ )‘
_ForeColor ° d ONLN dº j (8 6call is as follows:
° d ONLN d–( 3 Å * SetPort (myPort); ° d ONLN dÊ2 = ≥ *
savedFG := myPort^.fgColor; ° d ONLN d< G5 *
9 ForeColor (redColor); {or any other color} ° d ONLN d@P [ Ã *$ {...drawing takes place here...} ° d ONLN ded oè *K myPort^.fgColor := savedFG; {Manually stuff the old fgColor back.} ° d ONLN d±n yû *
N If (32BQD = TRUE) Then {32BQD is a flag that is made and set by} ° d ONLN d x É≤ *
R PortChanged (myPort); {the application; to set it, the application} ° d ONLN dSÇ çº *
T {needs to check _Gestalt for 32-Bit QuickDraw.}
° d ONLN d®ô • ≈ *&This Note also applies to the routine ° d ONLN dŒò ≈§ )≠
_BackColor ° d ONLN dÿô • )F.
° d ONLN d⁄Ω Ã j (Ë 6
What Works
° d ONLN dÂÿ ‰t *FThe easiest way to work with these limited colors is to use pictures. ° d ONLN d+ÿt‰⁄ ( íWhen you draw the ° d ONLN d=‰ I ( 6;images, you should draw into a picture. Then when you want ° d ONLN dx‰I⁄ ( g to draw the images into your ° d ONLN dïÒ ˝ ¢ ( 6 window or to a printer, call ° d ONLN d≤ ¢¸ ˆ )ä _DrawPicture ° d ONLN dæÒ ˆ˝E )T. Pictures work ° d ONLN dŒÒE˝⁄ )O well with the old-style colors, ° d ONLN dÓ˝ å (% 6Land you don’t need to worry about making sure that the forecolor is current ° d ONLN d:˝å ⁄ (%™
when you draw ° d ONLN dH q (1 6into your window. ° d ONLN dZ! -ó *TOnce you have the picture, you can use it to draw into the screen or to the printer ° d ONLN dÆ!ó-⁄ (Iµ
port. You can ° d ONLN dº. : R (V 6
also set the ° d ONLN d…- R9 ¶ ): WindowRecord ° d ONLN d’. ¶: Ø )Ts ° d ONLN d◊- Ø9 Ó ) windowPic ° d ONLN d‡. Ó:6 )? to equal your ° d ONLN dÔ-69ë )H
PictureHandle ° d ONLN d¸.ë:à )[ so updates ° d ONLN d.Ã:⁄ );are ° d ONLN d : F π (b 6 handled by the Window Manager. ¡ 4¡˘
. +Z-Developer Support , Palatino )K Center ( -ÛMay 1993 0 X 0
° d ONLN d * < 9H ( U Z#What Do Those Constants Mean Anyway
° d ONLN d $ E < Q £ *The correct values are ,
Courier
° d ONLN d < ] < i ~ * blackColor ° d ONLN d H ] Ñ i ê )H= ° d ONLN d K ] ® i ¥ )$33 ° d ONLN d N h < t ~ ( ê Z whiteColor ° d ONLN d Z h Ñ t ê )H= ° d ONLN d ] h ® t ¥ )$30 ° d ONLN d ` s < l ( õ ZredColor ° d ONLN d i s Ñ ä )H= ° d ONLN d k s ® ∫ )$205 ° d ONLN d o ~ < ä x ( ¶ Z
greenColor ° d ONLN d z ~ Ñ ä ä )H= ° d ONLN d | ~ ® ä ∫ )$341 ° d ONLN d Ä â < ï r ( ± Z blueColor ° d ONLN d ä â Ñ ï ä )H= ° d ONLN d å â ® ï ∫ )$409 ° d ONLN d ê î < † r ( º Z cyanColor ° d ONLN d ö î Ñ † ä )H= ° d ONLN d ú î ® † ∫ )$273 ° d ONLN d † ü < ´ ä ( « Z
magentaColor= ° d ONLN d Æ ü ® ´ ∫ )l137 ° d ONLN d ≤ ™ < ∂ ~ ( “ Z yellowColor ° d ONLN d æ ™ Ñ ∂ ä )H= ° d ONLN d ¿ ™ ® ∂ ¥ )$69
° d ONLN d √ ¡ < ÕL ( È Z9The following discussion is theoretical and was based on ° d ONLN d ¸ ¡L Õ˛ ( Èj#the color constants for the MPW 3.1 ° d ONLN d Õ < ŸP ( ı Z<interfaces. Well, those interfaces were wrong as far as the ° d ONLN d\ ÕP Ÿ˛ ( ın$color constants. The discussion will ° d ONLN dÅ Ÿ <  ª ( Zbe kept here to prove once ° d ONLN dú Ÿ ª ² )Aand for all that Macintosh programming sometimes is arbitrary and ° d ONLN dfi  < Ò¶ (
@ ˜ 0 @ @ ˜ ê @ @ ˜ ëåH @ ˜ RP @ ˜ ë–` @ ˜ íP` @ ˜ íRP @ ˜ ÃH @ Ó
@ Ó
@ Ó
@ Ó
@ Û @ Û Ä @ Û ò‡ @ Û • @ Û = @ Û
! @ Û % @ Û ò‡ @ Ó
@ Î @ Î @ Î @ Ò ¸ @ Ò Ä˝ @ Ò
c @ Ò
îí @ Ò
ê˜í @ Ò
êÑ @ Ò
êîí @ Ò
c @ Î @ Ë Ë Ë Ë
Ì yIJ
Ì DIJ
Ì Dâ0
Ì xâH
Ì Dâx
Ì Dâ@
Ì DâH
Ì xá0 Ë Ë Â Â Â Â Ù @ı ˙ ¸ áò ` $˛ ˙ ¸ ÑH Ä"$˛ ˙ âã1ÅHΔ$ù¿G3òé ˙ äLJAâ)(HÄDë$I ˙ S»3¡HË0ÚHÄDë<‚I ˙ R
I(0HÄÑë I ˙ "HJ@ÑI)(HÄÑë$I ˙ !à1ÄáàÊ$àÑÑêòâ
Ù @¸ ˘ Ó ˘ „ „ „ „ „ „ Ò Äı @˜ 0 @ à 3 ˜ ê ê @ D ˜ ìv1ëåH í9ú¿ Ó˜ TòIIRPí ™$â D˜ TêI9ë–a‰í ™$âÁíD˜ 4êIIíP`í D$â D˜ 4êIIíRPí D$â D ˜ I9ÃH D$Ñ¿ D Ò Ä¸ ˚ @Î @˙ † É
IR ° d ONLN d… ‘’e +ò¥Figure 1—Bit Definitions ° d ONLN d+Ì «˘s (  Table 1 Color-Bit Correlation
° d ONLN d ) 5 Ç *$Further Reference: T 4 T˘ ° d ONLN d B * N . +• ° d ONLN d B < N ç )Inside Macintosh ° d ONLN d % B ç N7 )Q!, Volume I, page I-173, QuickDraw ° d ONLN d G N * Z . ( v H• ° d ONLN d I N < ZÅ )<Technical Note M.IM.Copybits—Of Time and Space and _CopyBits ¡ 4¡˘
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < Å‘ ( õ Z.QD 9 - Palette Manager Changes in System 6.0.2
° d ONLN d / Ä < è á * QuickDraw
° d ONLN d : õ < ß q * Written by: ° d ONLN d F õ Ñ ß Œ )HGuillermo Ortiz ° d ONLN d V õæ ߲ ( √‹ October 1988 ° d ONLN d c ≥ < øl ( € Z>This Technical Note describes the changes and enhancements to ° d ONLN d ° ≥l ø˛ ( €ä the Palette Manager in System ° d ONLN d ø ø < À Ê ( Á Z#Software 6.0.2 and future versions. ˆ X ˆ
° d ONLN d „ < ˇ ª *4Application Palette
° d ONLN d ˜ <ö *MApplications now have the ability to define a default palette for the system ° d ONLN dD ö˛ (3∏to use when it needs ° d ONLN dY <# Û (? Z'to define the color environment (i.e., ° d ONLN dÄ Û#˛ )∑4when it creates a color window without an associated ° d ONLN dµ# </ ÷ (K Z"palette or displays a dialog box). ° d ONLN dÿ; <G2 *6The application palette feature is especially cool in ° d ONLN d;2G˙ )ˆ(cases where a color application uses old ° d ONLN d6;˙G˛ )»- ° d ONLN d7G <Sfi (o ZYstyle dialogs and alerts because without an application palette, the system will use the ° d ONLN dêGfiS˛ (o¸default ° d ONLN dòS <_ ˝ ({ Z)palette to define the color environment. ° d ONLN d¡S ˝_˛ )¡5 Since the system uses the default palette, the color ° d ONLN d˜_ <k ì (á Zenvironment may ° d ONLN d_ ìk Ω )Wchange ( ° d ONLN d_ Ωk œ )*will ° d ONLN d_ œk˛ ): change in 16-color mode) to cause some “cosmic” colors to ° d ONLN dNk <w ˆ (ì Z'appear in the active window. Defining ° d ONLN duk ˆw˛ )∫8a default application palette with two colors, black and ° d ONLN dÆw <É Ω (ü Zwhite, solves this problem. ° d ONLN d è <õ Ô *(If the system needs a palette to define ° d ONLN dÚè Ôõ˛ )≥9a color environment, it looks in the resource fork of the ° d ONLN d,ú <® î (ƒ Zapplication for the ,
Courier ° d ONLN d@õ îß ⁄ )X
'pltt' ID ° d ONLN dJõ ⁄ß ¯ )F= 0 ° d ONLN dNú ¯®˛ ) 8resource and uses the palette which it contains. If the ° d ONLN dá® <¥ ` (– Zsystem ° d ONLN dé® `¥˛ )$Ycannot find this resource in the application’s resource fork, it will use its own default ° d ONLN d˵ <¡ å (› Zpalette (resource ° d ONLN d˙¥ å¿ Ó )P'pltt' ID = 0 ° d ONLN dµ Ó¡Q )bin the System file) if ° d ONLN d µQ¡˛ )c&present, or, if necessary, it will use ° d ONLN dF¡ <Õ Î (È Z'the Palette Manager’s built-in palette. ° d ONLN dn⁄ <ʆ *>Once an application has set its color environment (by calling ° d ONLN d¨Ÿ†ÂÊ (æ
_InitMenus ° d ONLN d∂⁄ÊÊÙ )F, ° d ONLN d∏⁄ÙÊ˛ )or ° d ONLN dªÊ <Ú ó ( Z
_InitPalettes ° d ONLN d»Á óÛ ƒ )[
in weird ° d ONLN d“Á ƒÛ˛ )-Binstances when there are no menus) it can find the default palette ° d ONLN dÙ < o ( Z by calling ° d ONLN d Û oˇ> )3 GetPalette ( WindowPtr (-1) ) ° d ONLN d=Ù> ´ )œ or change the default ° d ONLN dTÙ´ ˛ )mpalette by calling ° d ONLN dg < £ () Z/SetPalette ( WindowPtr (-1), newDefPltt, true ) ° d ONLN dñ£
÷ ()¡. Note ° d ONLN dû÷
˛ )3that the ° d ONLN dß < ñ (6 Zinitialization of the ° d ONLN dΩ ñ) )Z Palette Manager with a call to ° d ONLN d‹
)o )ì
_InitMenus ° d ONLN dÊo· )F is contrary to the way ° d ONLN d˛·˛ )rInside ° d ONLN d <& m (B Z Macintosh ° d ONLN d m&N )1-, Volume V, The Palette Manager documents it.
° d ONLN d<> <M fi (i ZOne Palette, Many Ports
° d ONLN dTZ <f Ñ * You can now ° d ONLN d`Z Ñf* )H associate one palette with many ° d ONLN dÄY*ei )¶ CGrafPort ° d ONLN dâZifÜ )? and ° d ONLN déYÜe∑ ) CWindow ° d ONLN dïZ∑f˛ )1 records, thus ° d ONLN d§f <r ¶ (é Zsimplifying the use of ° d ONLN dªf ¶r˛ )jEa single palette with multiple ports and windows; System Software 6.0 ° d ONLN dr <~è (ö ZKand earlier require copies of the palette to use it with different windows. ¡ X¡
*<.QD 9 - Palette Manager Changes in System 6.0.2 (÷1 ) of 3 (Ï ZM.QD.PaletteManagerChanges ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† øx ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d )O *CAlthough this ability to associate one palette with multiple ports ° d ONLN d C O )⁄ ( Emand windows will allow the ° d ONLN d ^ * 6 P ( R 6
use of calls ° d ONLN d k * P 6 e )8like ,
Courier ° d ONLN d p ) e 5 π ) _PmForeColor ° d ONLN d | * π 6 “ )T and ° d ONLN d Å ) “ 5& ) _PmBackColor ° d ONLN d ç *& 6Q )T
, calling ° d ONLN d ó )Q 5¡ )+_ActivatePalette ° d ONLN d ß *¡ 6⁄ )p with ° d ONLN d ≠ 6 B@ ( ^ 6Ban off-screen port does nothing, and as a result, calling it with ° d ONLN d Ô 6@ B⁄ ( ^^!an off-screen port will associate ° d ONLN d B Né ( j 6Qthe palette with the port but will not cause any change in the color environment. ° d ONLN dc [ g *2One important implication of this feature is that ° d ONLN dï Z f[ )Ë
DisposeWindow ° d ONLN d¢ [[ gd )[ ( ° d ONLN d§ Zd fø )
_DisposWindow ° d ONLN d± [ø g⁄ )[) will ° d ONLN d∏ g s1 ( è 6=not dispose of the associated palette automatically since it ° d ONLN dı g1 s⁄ ( èO"may be allocated to other ports or ° d ONLN d s ƒ ( õ 6Iwindows. The only exception to this behavior is when an application has ° d ONLN da sƒ ⁄ ( õ‚used ° d ONLN df ã z ( ® 6_GetNewCWindow ° d ONLN dt Ä z å )b" to create the window, there is a ° d ONLN dñ ã= )ô'pltt' ° d ONLN dú Ä= åæ )* resource with the same ID ° d ONLN d∑ Äæ å⁄ )Åas the ° d ONLN dæ ç ô ‰ ( µ 6+window, and the application has not called ° d ONLN dÈ å ‰ ò1 )Ã _GetPalette ° d ONLN dÙ ç1 ôÅ )M for the window.
° d ONLN d ± ¿ w ( ‹ 6
Color Updates
° d ONLN d Õ Ÿ *1System version 6.0.2 also introduces a new call, ° d ONLN dD à ÿm ( ı7 _NSetPalette ° d ONLN dP Õm Ÿ⁄ )T, which complements ° d ONLN dd Ÿ  e ( 6 _SetPalette ° d ONLN do ⁄ e Ê s )M. ° d ONLN dr Ÿ s  « ) _NSetPalette ° d ONLN d~ ⁄ « Ê` )T has the same functionality as ° d ONLN dù Ÿ` Â≠ )ô _SetPalette ° d ONLN d® ⁄≠ Ê⁄ )M , but the ° d ONLN d≤ Ê Ú P ( 6CUpdates ° d ONLN d∫ Á P Û ˇ )8$ parameter has been modified from a ° d ONLN dfi Ê ˇ Ú0 )ØBoolean ° d ONLN d Á0 ÛM )1 to an ° d ONLN dÏ ÊM Ú~ ) Integer ° d ONLN dÛ Á~ Ûµ )1 as follows:
° d ONLN d ˇ
{ (& 6GPROCEDURE NSetPalette (dstWindow: WindowPtr; srcPalette: PaletteHandle; ° d ONLN dI < † +$
nCUpdates: INTEGER); ° d ONLN d^ Y (: 6
INLINE $AA95;
° d ONLN dl) 5 l * _NSetPalette ° d ONLN dx* l6 o )T ° d ONLN dy* o6 )$changes the palette associated with ° d ONLN dù)5Y )´ dstWindow ° d ONLN d¶*Y6j )? to ° d ONLN d™)j5∞ )
srcPalette ° d ONLN d¥*∞6⁄ )F
. It also ° d ONLN dø6 B` (^ 6@records whether the window wants to receive updates as a result ° d ONLN dˇ6`B⁄ (^~of a change to its color ° d ONLN dC O ¶ (k 6environment. If you want ° d ONLN d2B ¶N Â )é dstWindow ° d ONLN d;C ÂO Î )? ° d ONLN d<C ÎO⁄ ),to be updated whenever its color environment ° d ONLN diP \ W (x 6
changes, set ° d ONLN dvO W[ ñ )? nCUpdates ° d ONLN dP ñ\ ß )? to ° d ONLN dÉO ß[ ˚ ) pmAllUpdates ° d ONLN dèP ˚\ )T. If ° d ONLN dïP\⁄ )'you are only interested in updates when ° d ONLN dΩ\ h W (Ö 6 dstWindow ° d ONLN dΔ] Wi fi )? is the active window, set ° d ONLN d·\ fih )á nCUpdates ° d ONLN dÍ] i0 )? to ° d ONLN dÓ\0h} ) pmFgUpdates ° d ONLN d˘]}iã )M. ° d ONLN d¸]ãi⁄ )If you are only ° d ONLN d j v § (í 6interested in updates when ° d ONLN d'i §u „ )å dstWindow ° d ONLN d0j „v È )? ° d ONLN d1j Èvã ) is not the active window, set ° d ONLN dOiãu )¢ nCUpdates ° d ONLN dXj v⁄ )? to ° d ONLN d\v Ç e (ü 6 pmBkUpdates ° d ONLN dgw eÉ i )M.
° d ONLN diè ö ∏ (∂ 6 { NSetPalette Update Constants } ° d ONLN dä£ Æ ^ *pmNoUpdates = ° d ONLN dô£ ÑÆ ¢ )l$8000; ° d ONLN d†£ ®Æ ‰ )$ {no updates} ° d ONLN d≠≠ ∏ ^ (‘ 6pmBkUpdates = ° d ONLN dº≠ Ñ∏ ¢ )l$A000; ° d ONLN d√≠ ®∏% )${background updates only} ° d ONLN d›∑ ¬ ^ (fi 6pmFgUpdates = ° d ONLN dÏ∑ Ѭ ¢ )l$C000; ° d ONLN dÛ∑ ®¬% )${foreground updates only} ° d ONLN d
¡ à c (Ë 6pmAllUpdates = ° d ONLN d ¡ Ñà ¢ )l$E000; ° d ONLN d$¡ ®Ã È )$
{all updates}
° d ONLN d2◊ „ e ( 6 _SetPalette ° d ONLN d=ÿ e‰ ¯ )M! retains its syntax and function:
° d ONLN d_ ˚v ( 6FPROCEDURE SetPalette (dstWindow: WindowPtr; srcPalette: PaletteHandle; ° d ONLN dß˙ < õ +$
CUpdates: Boolean); ° d ONLN dª Y (+ 6
INLINE $AA95;
° d ONLN d… ' 7 *Note: ° d ONLN dœ <' ò )$The trap words for ° d ONLN d‚ ò& Ï )\ _NSetPalette ° d ONLN dÓ Ï' )T and ° d ONLN dÛ&P ) _SetPalette ° d ONLN d˛P'S )M ° d ONLN dˇS'a )are ° d ONLN da'è ) identical.
° d ONLN d? N g (j 6 CopyPalette
° d ONLN dZ eI *=PROCEDURE CopyPalette (srcPalette, dstPalette: PaletteHandle; ° d ONLN dYd <o ˙ +$
&srcEntry,dstEntry,dstLength: INTEGER); ° d ONLN dÄn y Y (ï 6
INLINE $AAA1; ¡ 4¡˘
*A2 ) of 3 )ı.QD 9 - Palette Manager Changes in System 6.0.2 +LM.QD.PaletteManagerChanges ˇX ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1988 / X / ,
Courier
° d ONLN d < ) ê ( F Z _CopyPalette ° d ONLN d ê *+ )T$ is a utility procedure that copies ° d ONLN d 0 + )j )õ dstLength ° d ONLN d 9 j *m )? ° d ONLN d : m *˛ ) entries from the source palette ° d ONLN d Z + < 7$ ( S Z1into the destination palette; the copy begins at ° d ONLN d ã *$ 6\ )ËsrcEntry ° d ONLN d ì +\ 7y )8 and ° d ONLN d ò *y 6¬ )
dstEntry, ° d ONLN d ¢ +¬ 7˛ )I
respectively. ° d ONLN d ± 7 < C ê ( ` Z _CopyPalette ° d ONLN d Ω 8 ê D€ )TJ will resize the destination palette when the number of entries after the ° d ONLN d 8€ D˛ ( `˘copy is ° d ONLN d D < P Ø ( l Zgreater than the original. ° d ONLN d* \ < h ê * _CopyPalette ° d ONLN d6 ] ê i ƒ )T
does not ° d ONLN d@ ] ƒ i ⁄ )4call ° d ONLN dE \ ⁄ hJ )_ActivatePalette ° d ONLN dU ]J i˛ )p$, so the application is free to do a ° d ONLN dz i < u¡ ( ë ZKnumber of palette changes without causing a series of intermediate changes ° d ONLN d≈ i¡ u˛ ( ëfl to the color ° d ONLN d“ v < Ç ( û Z)environment; the application should call ° d ONLN d˚ u Åt )»_ActivatePalette ° d ONLN d vt Dz )p after completing all palette ° d ONLN d) Ç < é f ( ™ Zchanges. ° d ONLN d2 õ < ß € *%If either of the palette handles are ° d ONLN dW ö € ¶ )üNIL ° d ONLN dZ õ ß ˜ ), ° d ONLN d\ ö ˜ ¶K ) _CopyPalette ° d ONLN dh õK ßè )T does nothing. ¡ X¡
(÷ Z.QD 9 - Palette Manager Changes in System 6.0.2 (÷3 ) of 3 (Ï ZM.QD.PaletteManagerChanges ˇ| ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R≈ R… x( +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ω ( {íDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 Ûe ( UÎ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
û? +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
ze ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < ŧ ( õ Z&QD 10 - Picture Comments—The Real Deal
° d ONLN d ' Ä < è á * QuickDraw
° d ONLN d 2 õ < ß t * Revised by: ° d ONLN d > õ Ñ ß )H
Joseph Maurer ° d ONLN d L õæ ߲ ( √‹ October 1992 ° d ONLN d Y ß < ≥ q ( œ Z Written by: ° d ONLN d e ß Ñ ≥ – )HGinger Jernigan ° d ONLN d u ß± ≥˛ ( œœ
November 1986 ° d ONLN d É ø < À ‹ ( Á ZChanges since March 1988: ° d ONLN d ù ø ‹ À> )†This Note (formerly ° d ONLN d ± ø> ÀÚ )b&titled “Optimizing for the LaserWriter ° d ONLN d ◊ øÚ À˛ )¥— ° d ONLN d ÿ À < ◊% ( Û Z-PicComments”) describes the picture comments ° d ONLN d À% ◊˛ )È,defined and interpreted by the Apple printer ° d ONLN d2 ◊ < „ ( ˇ Zdrivers. Most ° d ONLN d@ ◊ „˛ )CNof the picture comments are specific to PostScript, but we renamed the Note to ° d ONLN dè „ < Ôû ( ZLemphasize that LaserWriter printers are not necessarily PostScript devices, ° d ONLN d€ „û Ô˛ ( ºand that QuickDraw ° d ONLN dÓ Ô < ˚— ( ZLprinter drivers may implement their own picture comment handling. This Note ° d ONLN d: Ô— ˚˛ (Ôhas been ° d ONLN dC ˚ < (# ZUcompletely rewritten and incorporates all additional insights gained during the last ° d ONLN dò ˚ ˛ (#Ë
few years. ° d ONLN d£ < ` (/ ZWe are ° d ONLN d™ `˛ )$Qalso much more determined now to discourage the use of obsolete and problem-laden ° d ONLN d¸ < (; Z-(although still supported) picture comments, ° d ONLN d) ˛ )Ÿ,and we carefully point out known problems or ° d ONLN dV <+ ƒ (G Z limitations of each comment. V XV
° d ONLN dsP <_ è *4 Introduction
° d ONLN dÄl <x R *The ,
Courier ° d ONLN dÑk Rw É )QDProcs ° d ONLN dãl Éx ¿ )1
record (see ° d ONLN dòl ¿x )=Inside Macintosh ° d ONLN d®lx∑ )R" Volume I, page 197) reflects the ° d ONLN d l∑x˛ )•foundations of ° d ONLN dŸy <Ö ì (° Zthe architecture of ° d ONLN dÌy ìÖ Á )WQuickDraw. The ° d ONLN d¸x ÁÑ4 )T commentProc ° d ONLN dy4Ö˛ )M+ field points to a procedure that processes ° d ONLN d3Ü <í^ (Æ Z;picture comments, as included in a picture by means of the ° d ONLN dnÖ^ë§ (Æ|
PicComment ° d ONLN dxÜ§í· )F procedure ( ° d ONLN dÑÜ·í˛ )=Inside ° d ONLN dãí <û m (∫ Z Macintosh ° d ONLN dîí mû » )1 Volume I, page ° d ONLN d§í »û˛ )[>189). This allows applications to include application-specific ° d ONLN d„û <™" (Δ Z3additional information in the pictures they create. ° d ONLN d∑ <√ R *The ° d ONLN d∂ R¬ É )QDProcs ° d ONLN d"∑ É√G )1) record also is the key to understanding ° d ONLN dK∑G√˛ )ƒ#how Macintosh printer drivers work. ° d ONLN doƒ <– ¬ (Ï ZWhen the application calls ° d ONLN dä√ ¬œ )Ü
PrOpenPage ° d ONLN do )F and draws into the ° d ONLN d®ƒo–˛ )g printing grafPort, the printer ° d ONLN d«— <›Z (˘ Z9driver collects the drawing commands by hooking into the ° d ONLN d –Z‹ã (˘xQDProcs ° d ONLN d—ã›ÿ )1 of the printing ° d ONLN d—ÿ›˛ )Mport. In ° d ONLN d!fi <Í o ( Z particular, ° d ONLN d-fi oÍ Î )3 if an application calls the ° d ONLN dI› ÎÈ1 )|
PicComment ° d ONLN dSfi1Ͳ )F* procedure while drawing into the printing ° d ONLN d~Í <ˆ ( Z_grafPort, the printer driver gets a chance to capture and process the information contained in ° d ONLN d›Íˆ˛ (the ° d ONLN d·ˆ < X ( Zkind ° d ONLN d˜ X o ) and ° d ONLN d͈ o µ )
dataHandle ° d ONLN dÙ˜ µ Ô )F parameters. ° d ONLN d < Œ (7 Z During the development of the ° d ONLN d Œ˛ )í@original LaserWriter driver, it became obvious that applications ° d ONLN d` <': (C Z7should be able to take advantage of certain PostScript ° d ONLN dó:'˛ )˛)features that were not accessible through ° d ONLN d¡' <3 ¬ (O Zstandard QuickDraw calls, ° d ONLN d€' ¬3˛ )Ü@such as rotated text and graphics, dashed lines, fractional line ° d ONLN d 3 <?Å ([ ZCwidths, and smoothed polygons. Also, certain applications needed a ° d ONLN d_3Å?˛ ([üway to transmit their own ° d ONLN dy? <Kü (g ZJnative PostScript instructions to the printer. Picture comments seemed to ° d ONLN d√?üK˛ (gΩbe the ideal vehicle ° d ONLN dÿK <W — (s Z!for providing these capabilities. ° d ONLN d˙c <ob *?Unfortunately, there are conflicts with the device-independent ° d ONLN d 9cbo˛ (ãÄ nature of the Macintosh Printing ° d ONLN d Zo <{ ‰ (ó Z$Manager architecture. In this Note, ° d ONLN d ~o ‰{˛ )®8we still want to document picture comments as completely ° d ONLN d ∑{ <á ∂ (£ Zand correctly as possible; ° d ONLN d “{ ∂Რ)zDand we want to tell you how to use the best of their features, while ¡ X¡
(÷ Z&QD 10 - Picture Comments—The Real Deal (÷ˇ1 ) of 26 (Ï ZM.QD.PictComments ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø ö ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d )Q *Bmaintaining the important goal of device-independent printing and ° d ONLN d B Q )⁄ ( Eo all- purpose PICTs. (This is ° d ONLN d _ ) 5 ∫ ( Q 6#why it has such a painful history!) ° d ONLN d É A M Î **First, we give an overview of the picture ° d ONLN d ≠ A Î M⁄ )”,comments as currently implemented by Apple’s ° d ONLN d ⁄ M Y z ( u 6printer drivers. This ° d ONLN d M z Y⁄ )bFleads us immediately to the problem section “Cohabitation of QuickDraw ° d ONLN d7 Y e ˛ ( Å 6.and PostScript,” which also shows how to keep ° d ONLN de Y ˛ e⁄ )Ê,the QuickDraw and PostScript graphics states ° d ONLN dí e qà ( ç 6Zsynchronized during printing. Finally, we discuss all the picture comments by subject, in ° d ONLN dÏ eà q⁄ ( çÍthe ° d ONLN d q } ú ( ô 6order suggested by Table 1.
° d ONLN dÚ . V (7 L TextBegin ° d ONLN d¸ ç ú )_150 ° d ONLN d “ ◊ )E6 ° d ONLN d. )0
TTxtPicRec ° d ONLN d
Aã )?Begin text function ° d ONLN d" .% M (A LTextEnd ° d ONLN d* ç% ú )_151 ° d ONLN d. “% ◊ )E0 ° d ONLN d0% )0NIL ° d ONLN d4A%Ç )?End text function ° d ONLN dG$ ./ ] (K L StringBegin ° d ONLN dS$ ç/ ú )_152 ° d ONLN dW$ “/ ◊ )E0 ° d ONLN dY$/ )0NIL ° d ONLN d]$A/¢ )?Begin string delimitation ° d ONLN dx. .9 T (U L StringEnd ° d ONLN dÇ. ç9 ú )_153 ° d ONLN dÜ. “9 ◊ )E0 ° d ONLN dà.9 )0NIL ° d ONLN då.A9ô )?End string delimitation ° d ONLN d§8 .C X (_ L
TextCenter ° d ONLN dØ8 çC ú )_154 ° d ONLN d≥8 “C ◊ )E8 ° d ONLN dµ8C- )0
TTxtCenter ° d ONLN d¿8AC¶ )? Offset to center of rotation ° d ONLN dfiL .W e (s L
LineLayoutOff ° d ONLN dÏL çW ú )_155 ° d ONLN dL “W ◊ )E0 ° d ONLN dÚLW )0NIL ° d ONLN dˆLAW∏ )? Turn LaserWriter line layout off ° d ONLN dV .a d (} L LineLayoutOn ° d ONLN d%V ça ú )_156 ° d ONLN d)V “a ◊ )E0 ° d ONLN d+Va )0NIL ° d ONLN d/VAa∑ )? Turn LaserWriter line layout on ° d ONLN dO` k (á 6# ° d ONLN dQ` .k q )ClientLineLayout ° d ONLN db` çk ú )_157 ° d ONLN df` –k ⁄ )C16 ° d ONLN di`k) )2 TClientLL ° d ONLN ds`Ak® )?Customize line layout error ° d ONLN dïjAun *
distribution ° d ONLN d£t . W (õ L PolyBegin ° d ONLN d≠t ç ú )_160 ° d ONLN d±t “ ◊ )E0 ° d ONLN d≥t )0NIL ° d ONLN d∑tAò )?Begin special polygon ° d ONLN dŒ~ .â N (• LPolyEnd ° d ONLN d÷~ çâ ú )_161 ° d ONLN d⁄~ “â ◊ )E0 ° d ONLN d‹~â )0NIL ° d ONLN d‡~Aâè )?End special polygon ° d ONLN dıà .ì Y (Ø L
PolyIgnore ° d ONLN d à çì ú )_163 ° d ONLN dà “ì ◊ )E0 ° d ONLN dàì )0NIL ° d ONLN d
àAì∂ )? Ignore following polygon data ° d ONLN d)í .ù ^ (π L
PolySmooth ° d ONLN d4í çù ú )_164 ° d ONLN d8í “ù ◊ )E1 ° d ONLN d:íù& )0PolyVerb ° d ONLN dCíAùÜ )?Close, Fill, Frame ° d ONLN dWú .ß V (√ L PolyClose ° d ONLN daú çß ú )_165 ° d ONLN deú “ß ◊ )E0 ° d ONLN dgúß )0NIL ° d ONLN dkúAßà )?Close the polygon ° d ONLN d~∞ .ª Z (◊ L
DashedLine ° d ONLN dâ∞ çª ú )_180 ° d ONLN dç∞ ”ª ÷ )F- ° d ONLN dè∞ª3 )/ TDashedLine ° d ONLN dõ∞Aª∂ )? Draw following lines as dashed ° d ONLN dª∫ .≈ [ (· L
DashedStop ° d ONLN dΔ∫ ç≈ ú )_181 ° d ONLN d ∫ “≈ ◊ )E0 ° d ONLN dÃ∫≈ )0NIL ° d ONLN d–∫A≈ )?End dashed lines ° d ONLN d‚ƒ .œ b (Î L SetLineWidth ° d ONLN dÔƒ çœ ú )_182 ° d ONLN dÛƒ “œ ◊ )E4 ° d ONLN dıƒœ )0Point ° d ONLN d˚ƒAœ† )?Set fractional line widths ° d ONLN dÿ .„ o (ˇ LPostScriptBegin ° d ONLN d(ÿ ç„ ú )_190 ° d ONLN d,ÿ “„ ◊ )E0 ° d ONLN d.ÿ„ )0NIL ° d ONLN d2ÿA„≠ )? Set driver state to PostScript ° d ONLN dR‚ .Ì f ( LPostScriptEnd ° d ONLN da‚ çÌ ú )_191 ° d ONLN de‚ “Ì Ÿ )E0 ° d ONLN dh‚Ì )0NIL ° d ONLN dl‚AÌù )?Restore QuickDraw state ° d ONLN dÖÏ .˜ p ( LPostScriptHandle ° d ONLN dñÏ ç˜ ú )_192 ° d ONLN döÏ ”˜ ÷ )F- ° d ONLN dúϘ )/PSData ° d ONLN d§ÏA˜ü )?PostScript data in handle ° d ONLN dæˆ ( 6† ° d ONLN d¿ˆ . e )PostScriptFile ° d ONLN dœˆ ç ú )_193 ° d ONLN d”ˆ ” ÷ )F- ° d ONLN d’ˆ& )/FileName ° d ONLN dfiˆAõ )?FileName in data handle ° d ONLN dˆ (' 6† ° d ONLN d¯ . n )TextIsPostScript ° d ONLN d ç ú )_194 ° d ONLN d
“ ◊ )E0 ° d ONLN d )0NIL ° d ONLN d A )?$QuickDraw text is sent as PostScript ° d ONLN d8
(1 6† ° d ONLN d:
. Z )
ResourcePS ° d ONLN dE
ç ú )_195 ° d ONLN dI
“ ◊ )E8 ° d ONLN dK
9 )0
Type/ID/Index ° d ONLN dY
A∫ )?"PostScript data in a resource file ° d ONLN d} . l (; L
PSBeginNoSave ° d ONLN dã ç ú )_196 ° d ONLN dè “ ◊ )E0 ° d ONLN dë )0NIL ° d ONLN dïA ≠ )? Set driver state to PostScript ° d ONLN d¥ ) (E 6# ° d ONLN d∂ .) a ) SetGrayLevel ° d ONLN d√ ç) ú )_197 ° d ONLN d« “) ◊ )E4 ° d ONLN d… ) )0Fixed ° d ONLN dœ A)Ñ )?Call PostScript’s ,
Courier ° d ONLN d· Ñ)ß )Csetgray ° d ONLN dË ß)… )# operator ° d ONLN dÛ2 .= ^ (Y L RotateBegin ° d ONLN dˇ2 ç= ú )_200 ° d ONLN d2 “= ◊ )E4 ° d ONLN d2=) )0 TRotation ° d ONLN d2A=Ü )?Begin rotated port ° d ONLN d#< .G U (c L RotateEnd ° d ONLN d-< çG ú )_201 ° d ONLN d1< “G ◊ )E0 ° d ONLN d3<G )0NIL ° d ONLN d7<AGp )? End rotation ° d ONLN dEF .Q ` (m L RotateCenter ° d ONLN dRF çQ ú )_202 ° d ONLN dVF “Q ◊ )E8 ° d ONLN dXFQ )0Center ° d ONLN d_FAQ¶ )? Offset to center of rotation ° d ONLN d|Z e (Å 6# ° d ONLN d~Z .e f )
FormsPrinting ° d ONLN dåZ çe ú )_210 ° d ONLN dêZ “e ◊ )E0 ° d ONLN díZe )0NIL ° d ONLN dñZAe“ )?(Don’t clear print buffer after each page ° d ONLN død o (ã 6# ° d ONLN d¡d .o t )EndFormsPrinting ° d ONLN d“d ço ú )_211 ° d ONLN d÷d “o ◊ )E0 ° d ONLN dÿdo )0NIL ° d ONLN d‹dAoŒ )?$End forms printing after PrClosePage
° d ONLN d n z ¸ (ñ 6&______________________________________ ° d ONLN d (z Ü * †
° d ONLN d *z *Ü ¢ ) These comments are obsolete.
° d ONLN d GÜ í (Æ 6#
° d ONLN d IÜ *í Δ )#These comments are not recommended. ¡ 4¡˘ (÷ 62 ) of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇR ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d 5 < A¢ ( ] ZLMost of the comments in Table 1 were designed specifically for the original ° d ONLN d L 5¢ A˛ ( ]¿LaserWriter driver. ° d ONLN d ` A < M í ( i ZIn fact, the term ° d ONLN d r A í M )V LaserWriter ° d ONLN d } A M∏ )81 has been (and often still is) used in the sense ° d ONLN d Æ A∏ M˛ )Óof “PostScript ° d ONLN d Ω M < YJ ( u Z4printer,” and the LaserWriter driver is known to be ° d ONLN d Ò MJ Y˛ ( uh#basically a QuickDraw-to-PostScript ° d ONLN d Y < e| ( Å Z<translator. Meanwhile, however, QuickDraw-based LaserWriter ° d ONLN dQ Y| e˛ ( Åömodels came out, so we ° d ONLN dh e < q ≤ ( ç Zshould start being more ° d ONLN dÄ e ≤ q˛ )vBcareful in our terminology. This is why we insist on talking about ° d ONLN d√ q < }◊ ( ô ZWPostScript drivers or PostScript printers when a picture comment applies to PostScript. ° d ONLN d â < ï ó *QuickDraw printer ° d ONLN d- â ó ï˛ )[Fdrivers may implement their own picture comments, or some of the above ° d ONLN dt ï < ° v ( Ω Z
comments, ° d ONLN d~ ï v °˛ ):Pin order to provide additional capabilities. Certain third-party printer drivers ° d ONLN dœ ¢ < Æ t ( Z
implement ° d ONLN dŸ ¢ t Æk )8.text rotation, for example, by supporting the ,
Courier ° d ONLN d °k ≠˛ )˜TextBegin/TextCenter/ ° d ONLN d Æ < ∫ m ( ◊ ZTextEnd ° d ONLN d$ Ø m ª « )1 picture comments. ° d ONLN d7 « < ” ø ( Ô ZApple’s QuickDraw printer ° d ONLN dQ « ø ”˛ )ÉBdriver for the LaserWriter SC supports the following three picture ° d ONLN dî ” < fl o ( ˚ Z comments:
° d ONLN dü Î R ˆ â +
LineLayoutOff ° d ONLN d≠ Î ± ˆ ¿ )_155 ° d ONLN d± Î ˆ ˆ ˚ )E0 ° d ONLN d≥ Î& ˆ4 )0NIL ° d ONLN d∑ În ˆÂ )H Turn LaserWriter line layout off ° d ONLN dŸ ı R à ( p LineLayoutOn ° d ONLN dÊ ı ± ¿ )_156 ° d ONLN dÍ ı ˆ ˚ )E0 ° d ONLN dÏ ı& 4 )0NIL ° d ONLN d ın ‰ )H Turn LaserWriter line layout on ° d ONLN d ˇ R
Ü (& p SetLineWidth ° d ONLN d ˇ ±
¿ )_182 ° d ONLN d" ˇ ˆ
˚ )E4 ° d ONLN d$ ˇ&
; )0Point ° d ONLN d* ˇn
– )HSet fractional line widths.
° d ONLN dF <! Ò (= Z"The ImageWriter LQ driver and the ° d ONLN dh Ò!˛ )µ7first versions of the StyleWriter driver (prior to 7.2) ° d ONLN d†" <. ç (J Zimplement the ° d ONLN dÆ! ç- Ë )Q
LineLayoutOff ° d ONLN dª" Ë. )[ and ° d ONLN d¿! -_ )# LineLayoutOn ° d ONLN dÃ"_.Œ )T picture comments. ° d ONLN dfl"Œ.˛ )oEven the ° d ONLN dË. <: (V Z.ImageWriter driver reacts to picture comments:
° d ONLN dF RQ ü +BitMapThinningOff ° d ONLN d*F ±Q ≈ )_1000 ° d ONLN d/F ˆQ ˚ )E0 ° d ONLN d1F&Q4 )0NIL ° d ONLN d5FnQÂ )H Turn off hi-res bitmap thinning ° d ONLN dVP R[ û (w pBitMapThinningOn ° d ONLN dgP ±[ ≈ )_1001 ° d ONLN dlP ˆ[ ˚ )E0 ° d ONLN dnP&[4 )0NIL ° d ONLN drPn[‰ )H Turn on hi-res bitmap thinning
° d ONLN dëf <r* (é Z1The ImageWriter driver does the same toggling of ° d ONLN d¬f*r˛ )Ó,the “bitmap thinning” of fat bitmaps in Best ° d ONLN dÔs < ^ (õ Zmode, ° d ONLN dıs ^ )"when it encounters a ° d ONLN d
r ~ )l TextBegin ° d ONLN ds )? or ° d ONLN dr ~N )TextEnd ° d ONLN d sNÒ )1 comment (undocumented feature ° d ONLN d<sÒ˛ )£— ° d ONLN d= <㶠(ß ZInever mind!). The ImageWriter LQ driver handles these comments similarly. ° d ONLN dáó <£Ô *YThe current StyleWriter driver (version 7.2.2) and the personal LaserWriter LS driver do ° d ONLN d‡óÔ£˛ (ø
not ° d ONLN d‰£ <Ø Á (À Z$support any picture comments at all. ° d ONLN d
ª <« ¶ *The point of all this is: ° d ONLN d$” Öfl¥ +I4It is impossible to determine which picture comments ° d ONLN dYfl ∞Îä ++ &are supported by which printer driver. ° d ONLN dĘ <— ( ZUIn other words, your application should never assume a particular picture comment is ° d ONLN d’˜—˛ ( Ô
available, ° d ONLN d‡ < O (+ Zbut ° d ONLN d‰ O˛ )Vyour application also should not defeat the device-independent design of the Macintosh ° d ONLN d; <V (7 Z>printing architecture by writing printer driver–specific code! ° d ONLN d{( <4 ® *Of course, you know ( ° d ONLN dê( ®4 ˘ )lInside Macintosh ° d ONLN d†( ˘4ä )Q Volume II, page 152) that the ° d ONLN dø(ä4€ )ëhigh byte of the ° d ONLN d–'€3˛ )QprStl ° d ONLN d÷5 <A @ (] Z. ° d ONLN d◊4 @@ \ )wDev ° d ONLN d€5 \A Ñ )
field of ° d ONLN dÂ5 ÑA˛ )(Sthe print record identifies a printer driver species, and that a value of $03 tells ° d ONLN d 9A <MÈ (i Z]you the printer driver belongs to the PostScript LaserWriter driver ancestry. As a matter of ° d ONLN d ñAÈM˛ (ifact, ° d ONLN d úM <Y¨ (u ZPmany applications use this information to achieve special printing features not ° d ONLN d ÏM¨Y˛ (u available through ° d ONLN d ˛Y <e Œ (Å Z the Printing Manager interface. ° d ONLN d
q <}R *6And, of course, you also know that we don’t like this ° d ONLN d
TqR}˛ (ôp!idea. One reason is future system ° d ONLN d
v} <âî (• ZLsoftware may allow spool files to be redirected to a printer other than the ° d ONLN d
¬}îⲠ(•≤one chosen when you ° d ONLN d
÷â <ïfi (± ZUsent your printing instructions (including picture comments). Another reason is that ° d ONLN d +âfiï˛ (±¸picture ¡ X¡
(÷ Z&QD 10 - Picture Comments—The Real Deal (÷ˇ3 ) of 26 (Ï ZM.QD.PictComments ˇ Ó ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d )´ *Rcomments usually are included in PICTs; documents containing such pictures should ° d ONLN d R ´ )⁄ ( E…
print with ° d ONLN d ] ) 5 b ( Q 6optimal results ° d ONLN d m ) b 5⁄ )JJon any printer configuration. And, finally, you never know what the future ° d ONLN d ∏ 5 A H ( ] 6
holds for ° d ONLN d ¬ 5 H A⁄ )0Nyou, in terms of new printing devices or new printer drivers—or a new printing ° d ONLN d A M R ( i 6
architecture! ° d ONLN d Y e z *Instead, if a picture ° d ONLN d5 Y z e⁄ )bG(i.e., a sequence of imaging instructions) contains picture comments to ° d ONLN d} e q ® ( ç 6 enhance the output on devices ° d ONLN dõ e ® q⁄ )ê>that support them, it should also contain a standard QuickDraw ° d ONLN d⁄ q }w ( ô 6Mrepresentation as a fallback solution, in case the rendering device does not ° d ONLN d' qw }⁄ ( ôïrecognize the picture ° d ONLN d= } â~ ( • 6Bcomments. The design and implementation of these picture comments ° d ONLN d }~ â⁄ ( •úshould incorporate ° d ONLN dí â ï¶ ( ± 6Uconventions to make this cohabitation of two representations in one picture possible.
° d ONLN dË ≠ º4 *'(Cohabitation of QuickDraw and PostScript
° d ONLN d » ‘ ∫ *Device-Independent Pictures ° d ONLN d- · Ì „ *'We can think of the Printing Manager’s ,
Courier ° d ONLN dT ‡ „ Ï) )À
PrOpenPage ° d ONLN d^ ·) ÌD )F and ° d ONLN dc ‡D Ïë ) PrClosePage ° d ONLN dn ·ë Ì∞ )M calls ° d ONLN du ·∞ Ì⁄ ) as being ° d ONLN d~ Ó ˙ h ( 6analogous to the ° d ONLN dè Ì h ˘ µ )P OpenPicture ° d ONLN dö Ó µ ˙ ∏ )M ° d ONLN dõ Ó ∏ ˙ Õ )and ° d ONLN dü Ì Õ ˘! ) ClosePicture ° d ONLN d´ Ó! ˙⁄ )T% calls (which, by the way, reminds us ° d ONLN d— ˚ c (# 6to never call ° d ONLN dfl ˙ c ∞ )K OpenPicture ° d ONLN dÍ ˚ ∞ Á )M between ° d ONLN dÛ ˙ Á- )7
PrOpenPage ° d ONLN d˝ ˚-N )F and ° d ONLN d ˙Nõ )! PrClosePage ° d ONLN d
˚õΩ )M; see ° d ONLN d ˚Ω⁄ )"Inside ° d ONLN d I (/ 6 Macintosh ° d ONLN d# I± )1J Volume II, page 160). In both cases, a stream of imaging instructions is ° d ONLN dm±⁄ (/œrecorded ° d ONLN dv ¥ (; 6 for deferred rendering. We want ° d ONLN dñ ¥ ⁄ )ú<to create pictures that include both QuickDraw and optimized ° d ONLN d” +2 (G 6>PostScript representations so that we obtain the best results ° d ONLN d 2+⁄ (GP"in all circumstances. We must take ° d ONLN d4+ 7 – (S 6'special care for third-party QuickDraw ° d ONLN d[+ –7⁄ )∏8printer drivers that support picture comments originally ° d ONLN dî7 C « (_ 6%intended for PostScript devices only. ° d ONLN d∫O [ • * Let’s start with the easy ones. ° d ONLN d⁄h t ú *The two picture comments ° d ONLN dÛg ús )ÑPostScriptBegin ° d ONLN dht )i and ° d ONLN dg sy )
getPicProc ° d ONLN d épöy )F, ° d ONLN d"éyöê ) and ° d ONLN d&çêô÷ )
putPicProc ° d ONLN d0é÷ö⁄ )F. ° d ONLN d2ö ¶ ¸ (¬ 6.This means that QuickDraw’s text, line, shape ° d ONLN d`ö ¸¶⁄ )‰*(Rects, RoundRects, Ovals, Arcs, Polygons) ° d ONLN d㶠≤R (Œ 6?and bitmap drawing calls don’t have any effect in the printing ° d ONLN d ¶R≤⁄ (ŒpgrafPort when enclosed by ° d ONLN d‰≤ æ Å (€ 6PostScriptBegin ° d ONLN dÛ≥ Åø á )i ° d ONLN dÙ≥ áø ü )and ° d ONLN d¯≤ üæ ˙ )
ÎG S *1a. ignores the QuickDraw clipping region between ° d ONLN d FRG ) TextBegin ° d ONLN d %GGS^ )? and ° d ONLN d *F^Rè )TextEnd ° d ONLN d 2T ` ï (| 6b. ignores the QuickDraw ° d ONLN d KS ï_ Õ )}CopyBits ° d ONLN d ST Õ`& )8 instruction within ° d ONLN d gS&_ù )YTextBegin/TextEnd ° d ONLN d yl x 0 (î 6This ° d ONLN d ~l 0x⁄ )[way, a bitmap representation of the rotated text can be included in the picture. It will be ° d ONLN d ⁄y Ö \ (° 6
used only if ° d ONLN d Áy \Ö q )Dthe ° d ONLN d Îx qÑ Ë )TextBegin/TextEnd ° d ONLN d ¸y ËÖ⁄ )w, comments are not supported. Conversely, the ° d ONLN d )Ö ëI (≠ 6>QuickDraw commands required to draw the text to be rotated by ° d ONLN d gÖIë⁄ (≠g the printer driver are “hidden” ¡ 4¡˘
(÷ 64 ) of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d < ) € ( E Z from QuickDraw by setting the ° d ONLN d € )˛ )ü8clipping region to empty, which is ignored by the driver ° d ONLN d W ) < 5 ∑ ( Q Zsupporting the comments. ° d ONLN d p A < M *-The polygon picture comments provide another ° d ONLN d ù A M˛ )‚/solution to the problem, in form of the special ° d ONLN d Õ N < Z j ( v Zcomment ,
Courier ° d ONLN d ’ M j Y ∞ ).
PolyIgnore ° d ONLN d fl N ∞ Z0 )F . It allows one to include a ° d ONLN d ¸ N0 Z˛ )Ä(QuickDraw representation of the smoothed ° d ONLN d% Z < f l ( Ç Z polygon, ° d ONLN d. Z l f˛ )0Mignored by a driver that supports polygon smoothing (such as via PostScript’s ° d ONLN d| f < r _ ( è Zcurve ° d ONLN dÅ g _ s d )# ° d ONLN dÇ g d s˛ )Moperator). And for filled polygons, QuickDraw’s region concept works around a ° d ONLN d– s < ó ( õ ZHconflict of who owns which polygon (see sample code later in this Note). ° d ONLN d ã < óÀ *SSome picture comments (such as the line layout comments) do not require a fallback ° d ONLN dl ãÀ ó˛ ( ≥È solution in ° d ONLN dx ó < £' ( ø Z4case they are not supported by a printer driver; or ° d ONLN d¨ ó' £˛ )Î/the feature, if absent, is not a big loss (such ° d ONLN d‹ § < ∞ J ( à Zas ° d ONLN dfl £ J Ø û ) SetLineWidth ° d ONLN dÎ § û ∞ ¶ )T, ° d ONLN dÌ § ¶ ∞˛ )Dprovided you use it only for widths smaller than one 72-dot-per-inch ° d ONLN d2 ∞ < º Æ ( ÿ Z(dpi) QuickDraw pixel). ° d ONLN dK … < ’ * But for the picture comments ° d ONLN dh » ‘É )¥DashedLine/DashedStop ° d ONLN d} …É ’™ )ì and ° d ONLN dÇ »™ ‘˛ )' RotateBegin/ ° d ONLN dè ’ < · ÷ ( ˛ ZRotateCenter/RotateEnd ° d ONLN d• ÷ ÷ ‚‘ )ö5, there is no general solution to the “cohabitation” ° d ONLN d⁄ ÷‘ ‚˛ )˛problem; ° d ONLN d„ ‚ < ÓB (
Z8and we are distressed about it. It is obvious that they ° d ONLN d ‚B Ó˛ (
`%have been defined with the PostScript ° d ONLN dA Ó < ˙ ≈ ( Z LaserWriter driver in mind, ° d ONLN d] Ó ≈ ˙˛ )â?without anticipating a future furnished by some 150 third-party ° d ONLN dù ˙ <´ (" ZPprinter drivers. The only way to include both representations in these cases is ° d ONLN dÌ ˙´˛ ("…indeed to assume ° d ONLN d˛ < x (. Z
PostScriptEnd ° d ONLN dl ˛ )[* comments can be used to “comment out” the ° d ONLN dó <+ ª (G ZQuickDraw representation. ° d ONLN d±7 <C Ü *Even under the ° d ONLN d¿7 ÜC˛ )JMabove assumption, we still need a trick to prevent the QuickDraw calls within ° d ONLN dC <O≥ (k ZHthe scope of the picture comments from showing up when the comments are ° d ONLN dVC≥O˛ (k—not recognized. ° d ONLN dfO <[ ˝ (w Z(Fortunately, early Macintosh developers ° d ONLN déO ˝[˛ )¡5discovered a QuickDraw feature that, unintentionally, ° d ONLN dƒ\ <h ] (Ñ Zsolves ° d ONLN dÀ\ ]h> )!,the problem. Passing the “magic” mode 23 to ° d ONLN d˜[>go )·PenMode ° d ONLN d˛\oh˛ )1 inhibits QuickDraw’s normal ° d ONLN dh <t ì (ê Zdrawing, but still ° d ONLN d.h ìt˛ )WIlets the LaserWriter driver see the drawing instructions come through the ° d ONLN dxt <Ä» (ú ZTbottlenecks, so that it can translate them into PostScript. Note that this pen mode ° d ONLN dÃt»Ä˛ (úÊ
always has ° d ONLN d◊Ä <å£ (® ZIbeen undocumented, and that using it was considered a compatibility risk ° d ONLN d Ä£å˛ (®¡and frowned upon ° d ONLN d1å <ò∑ (¥ ZOfor some time. Given the current state of affairs, however, there is no reason ° d ONLN dÄå∑ò˛ (¥’
anymore to be ° d ONLN déò <§ è (¿ Zparanoid about it. ° d ONLN d°≥ <øV *-Keeping QuickDraw and PostScript Synchronized ° d ONLN dœÀ <◊ œ * There are two situations, in ° d ONLN dÏÀ œ◊˛ )ì8the context of picture comments, where the design of the ° d ONLN d %◊ <„Ó (ˇ Z[PostScript LaserWriter driver requires special precautions from the application programmer. ° d ONLN d Ç <¸ *+First, certain QuickDraw instructions like ° d ONLN d ≠Ô˚# )ÀMove ° d ONLN d ±#¸+ ) , ° d ONLN d ≥Ô+˚U )MoveTo ° d ONLN d πU¸^ )*, ° d ONLN d ªÔ^˚à ) PenPat ° d ONLN d ¡à¸ß )*, and ° d ONLN d «Ôß˚ÿ ) PenSize ° d ONLN d Œÿ¸˛ )1 change ° d ONLN d ÷˝ < / (% Z5the state of the grafPort, without going through the ° d ONLN d
¸/` )ÛQDProcs ° d ONLN d
˝` — )1 bottleneck procedures. ° d ONLN d
*˝— ˙ )qA Macin ° d ONLN d
1˝˙ ˛ ))- ° d ONLN d
2 < ˇ (1 Z(tosh printer driver takes these changes ° d ONLN d
Z ˇ˛ )√3into account only at the time it executes an actual ° d ONLN d
é <"z (> ZAdrawing instruction. Remember, the printer driver hooks into the ° d ONLN d
œz!´ (>òQDProcs ° d ONLN d
÷´"˛ )1 to get execution ° d ONLN d
Ë# </ S (K Ztime ° d ONLN d
Ì# S/@ )0and only “sees” instructions coming through the ° d ONLN d "@.q )ÌQDProcs ° d ONLN d $#q/Ú )1. Nothing is wrong with it ° d ONLN d >#Ú/˛ )Å— ° d ONLN d ?/ <; Ì (W Z%unless PostScript code is woven into ° d ONLN d d/ Ì;˛ )±7the graphics instructions by means of picture comments. ° d ONLN d ú; <G ´ (c Z(Note that PostScript ° d ONLN d ≤; ´G˛ )o?code may be generated transparently when the LaserWriter driver ° d ONLN d ÚG <SÙ (o Z\encounters certain picture comments.) If the PostScript code assumes that the current state ° d ONLN d NGÙS˛ (oof ° d ONLN d QS <_â ({ ZDthe grafPort corresponds to what you expect it to be, then you have ° d ONLN d ïSâ_˛ ({ßto flush the state of the ° d ONLN d Ø_ <ké (á ZIgrafPort explicitly before inserting the PostScript code. This is easier ° d ONLN d ¯_ék˛ (á¨than it sounds; just do ° d ONLN d
l <x (î Z,something inoffensive that goes through the ° d ONLN d
<kwä )fiQDProcs.lineProc ° d ONLN d
Lläx˛ )p bottleneck, like in the ° d ONLN d
ex <Ñ Ω († Z following utility procedure: ¡ X¡
*6&QD 10 - Picture Comments—The Real Deal (÷ˇ5 ) of 26 (Ï ZM.QD.PictComments ˇö ◊# ˇ ˇˇˇˇ # ◊
J{ This routine causes the state of the Printing Manager's grafPort to be } ° d ONLN d i 1 <ä *
J{ flushed out to the LaserWriter, by making a dummy call through the } ° d ONLN d ¥ ; Fä *
J{ QDProcs.lineProc bottleneck. Pen size and pen location are preserved. } ° d ONLN d ˇ O Z 6 * VAR ° d ONLN d Y d ê *
penInfo: PenState; ° d ONLN d m x @ * BEGIN ° d ONLN d( w Çè *
K GetPenState(penInfo); { Save pen size. } ° d ONLN dt Å åè *
K PenSize(0,0); { Make it invisible. } ° d ONLN d¿ ã ñè *
K Line(0,0); { Go through QDProcs.lineProc. } ° d ONLN d ï †è *
K PenSize(penInfo.pnSize.h, penInfo.pnSize.v); { Restore pen size. } ° d ONLN dX ü ™ ; *
END;
° d ONLN d` µ ¡ ï *Another unwanted effect ° d ONLN dx µ ï ¡⁄ )}Cis related to the PostScript LaserWriter driver’s multiple internal ° d ONLN dº ¡ Õ ‰ ( È 6(buffering of generated PostScript code. ° d ONLN d‰ ¡ ‰ Õ⁄ )Ã.The PostScript code generated for text drawing ° d ONLN d Õ Ÿ § ( ı 6 instructions (which usually ° d ONLN d/ Õ § Ÿ⁄ )å:involves font queries and, sometimes, font downloading) is ° d ONLN dj Ÿ Â/ ( 69buffered independently from the PostScript code inserted ° d ONLN d£ Ÿ/ Â⁄ (M by means of picture comments. In ° d ONLN dƒ Â Ò ÷ (
° d ONLN d"! , ≥ * PROCEDURE FlushPostScriptState; ° d ONLN dB+ 6Ö *
I{ This routine flushes the buffer maintained by the LaserWriter driver. } ° d ONLN då5 @Ö *
I{ All PostScript, generated either by the app or by the LaserWriter } ° d ONLN d÷? JÖ *
I{ driver, will be sent to the device. } ° d ONLN d I T @ *
BEGIN ° d ONLN d)S ^ Í *
* PicComment(PostScriptBegin, 0, NIL); ° d ONLN dT] h ‡ *
( PicComment(PostScriptEnd, 0, NIL); ° d ONLN d}g r ; *
END;
° d ONLN dÖ} â “ *'In the following discussion of picture ° d ONLN d¨} “â⁄ )∫6comments, we’ll refer to these two utility routines as ° d ONLN d„â ï Q (± 6 appropriate.
° d ONLN d≠ º s *'
Text Rotation
° d ONLN d˛… ’ W * Comments: ° d ONLN d» `‘ ü )H TextBegin ° d ONLN d… ü’ ¶ )?, ° d ONLN d» ¶‘ Ï )
TextCenter ° d ONLN d … Ï’ Û )F, ° d ONLN d » Û‘$ )TextEnd ° d ONLN d'· Ì Ñ ( 6These comments give ° d ONLN d;· ÑÌ⁄ )lIaccess to PostScript’s capabilities of rotating, flipping, and justifying ° d ONLN dÖÌ ˘∞ ( 6Ttext. They are intended for applications likely to be used with PostScript printers ° d ONLN dŸÌ∞˘⁄ (Œ(such as ° d ONLN d‚˘ = (! 67desktop publishing and advanced drawing applications), ° d ONLN d˘=⁄ (![but which don’t want to use ° d ONLN d5 X (- 6EPostScript explicitly. Note that some non-PostScript printer drivers ° d ONLN dzX⁄ (-vsupport these comments as ° d ONLN dî Ï (9 6,well. For situations where the comments are ° d ONLN d¿ Ï ⁄ )‘/not supported (such as the QuickDraw screen, or ° d ONLN d ) π (E 6!most QuickDraw printer drivers), ° d ONLN d π)g )°"you must provide a bitmap represen ° d ONLN d 4 g)⁄ )Ætation of the rotated text ° d ONLN d O) 5 g (Q 6as an alternative. ° d ONLN d cA M … *%Let’s look at sample code right away.
° d ONLN d âY d£ *OUSES PicComments; { See Appendix; defines constants for just and flip and } ° d ONLN d Ÿc n£ *
O { the structures referred to by TTxtPicHdl and TCenterHdl.} ¡ 4¡˘
*L6 ) of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇº ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d < (1 ( D Z1PROCEDURE QDStringRotation(s: Str255; ctr: Point; ° d ONLN d 3 ' < 2ö *
F just, flip: Integer; rot: Fixed); EXTERNAL; ° d ONLN d z 1 < <« *
O{ This routine should generate a bitmap of the rotated and flipped text } ° d ONLN d ; < F« *
O{ and use CopyBits to draw it to the grafPort. Left as an exercise ... } ° d ONLN d O < Z¬ *NPROCEDURE DrawXString(s: Str255; ctr: Point; just, flip: Integer; rot: Fixed); ° d ONLN di Y < d« *
O{ Draws the string s rotated by rot degrees around the current point, offset } ° d ONLN dπ c < n« *
O{ by ctr, justifying and flipping according to the just and flip parameters. } ° d ONLN d m < x« *
O{ If the printer driver supports the TextBegin, TextCenter, and TextEnd } ° d ONLN dY w < Ç« *
F hT: TTxtPicHdl; { Defined in PicComments.p - see Appendix. } ° d ONLN dj ≥ < æ · *
! hC: TCenterHdl; { –"– } ° d ONLN då Ω < » • *
zeroRect: Rect; ° d ONLN d¢ « < “ å *
pt: Point; ° d ONLN d≥ — < ‹ π *
oldClip: RgnHandle; ° d ONLN dÕ Â < d * BEGIN ° d ONLN d÷ Ô < ˙; *
3 GetPen(pt); { to preserve the pen position } ° d ONLN d
<J *6 hT := TTxtPicHdl(NewHandle(SizeOf(TTxtPicRec))); ° d ONLN dA
<J *
6 hC := TCenterHdl(NewHandle(SizeOf(TCenterRec))); ° d ONLN dx <"∏ *
L { No error handling: if these fail, we are in deep trouble anyway ...} ° d ONLN d≈! <, ¥ *
WITH hT^^ DO BEGIN ° d ONLN dfi+ <6 √ *
tJus := just; ° d ONLN d˙5 <@ √ *
tFlip := flip; ° d ONLN d? <JÆ *
J tAngle := - FixRound(rot); { I like counterclockwise better. } ° d ONLN dbI <T ı *
% tLine := 0; { reserved } ° d ONLN dàS <^Ü *
B tCmnt := 0; { used internally by the printer driver } ° d ONLN dÀ] <h “ *
tAngleFixed := - rot; ° d ONLN dÍg <r n *
END; ° d ONLN dıq <| ‹ *
hC^^.y := Long2Fix(ctr.v); ° d ONLN d{ <Ü ‹ *
hC^^.x := Long2Fix(ctr.h); ° d ONLN d7è <ö^ *: PicComment(TextBegin,SizeOf(TTxtPicRec),Handle(hT)); ° d ONLN drô <§c *
; PicComment(TextCenter,SizeOf(TCenterRec),Handle(hC)); ° d ONLN dÆ£ <Ƨ *
H { PostScript graphics state now has rotated/flipped coordinates. } ° d ONLN d˜∑ <¬ ¥ * oldClip := NewRgn; ° d ONLN d¡ <Ã Ø *
GetClip(oldClip); ° d ONLN d(À <÷ ‹ *
SetRect(zeroRect,0,0,0,0); ° d ONLN dI’ <‡∏ *
L ClipRect(zeroRect); { Hides the following DrawString from QuickDraw } ° d ONLN dñfl <Íw *
? DrawString(s); { in the rotated PostScript environment. } ° d ONLN d÷È <Ù Ê *
" ClipRect(oldClip^^.rgnBBox); ° d ONLN d˘˝ <≥ *K { Now the "fallback" bitmap representation; see the comments above } ° d ONLN dE <w *
? { at the declaration of the QDStringRotation procedure. } ° d ONLN dÖ < , *
0 QDStringRotation(s, ctr, just, flip, rot); ° d ONLN d∂% <0« *O PicComment(TextEnd,0,NIL); { Set environment back to the original state } ° d ONLN d 9 <D ◊ * DisposHandle(Handle(hT)); ° d ONLN d &C <N ◊ *
DisposHandle(Handle(hC)); ° d ONLN d FW <b^ *: MoveTo(pt.h,pt.v); { to preserve the pen position } ° d ONLN d Åa <l _ *
END;
° d ONLN d âw <É ∑ *The preceding discussion ° d ONLN d ¢w ∑ɲ ){Aabout including both QuickDraw and PostScript representations and ° d ONLN d ‰É <è¡ (´ ZQthe comments included in the source code say it all: The conventions tied to the ° d ONLN d
° d ONLN d ) W * TextBegin ° d ONLN d W * n )? and ° d ONLN d n ) ü )TextEnd ° d ONLN d ü *µ )1; picture comments allow you to take advantage of a printer ° d ONLN d P µ *⁄ ( F”driver’s ° d ONLN d Y * 6 ˙ ( R 61implementation of high-resolution text rotation, ° d ONLN d ä * ˙ 6⁄ )‚.while including a bitmapped representation for ° d ONLN d π 6 B “ ( ^ 6%where the comments are not supported. ° d ONLN d fl N Z ô *Some Additional Hints ° d ONLN d ı f r *• ° d ONLN d ˜ f % râ )
+The angle is measured in degrees (0..360), ° d ONLN d¯ ó Û £C )Œand passed as a ° d ONLN d ñC ¢f )PFixed ° d ONLN d
óf £⁄ )# type number (that is, if ° d ONLN d' § % ∞ V ( Ã C taken as a ° d ONLN d2 £ V Ø á )1LongInt ° d ONLN d9 § á ∞ ™ )1 value, ° d ONLN dA § ™ ∞⁄ )#?you have to divide it by 65536 to obtain the angle in degrees). ° d ONLN dÅ ± % Ω : ( Ÿ CFor ° d ONLN dÖ ± : Ω! )0integer angles, it is possible to use a reduced ° d ONLN dµ ∞! ºg )Á
TTxtPicRec ° d ONLN dø ±g Ω⁄ )F structure that does not ° d ONLN dÿ æ % w ( Ê C contain the ° d ONLN d‰ Ω w … Ø )RtRotFrac ° d ONLN dÏ æ Ø ≈ )8* field. The PostScript LaserWriter driver ° d ONLN d æ≈ ⁄ ( Ê„uses ° d ONLN d % ÷ ú ( Û CGetHandleSize(hT) ° d ONLN d, À ú ◊  )w to determine ° d ONLN d: À  ◊⁄ )I/whether it must use the fractional angle in the ° d ONLN dj ◊ % „ ] ( CtRotFrac ° d ONLN dr ÿ ] ‰ ˘ )8# field. To be safe, always set the ° d ONLN dï ◊ ˘ „ )útRot ° d ONLN dô ÿ ‰< )
field to ° d ONLN d£ ◊< „∫ )'FixRound(tRotFrac) ° d ONLN dµ ÿ∫ ‰Ω )~ ° d ONLN d∂ ÿΩ ‰⁄ )if you ° d ONLN dΩ Â % Ò ä (
Cgo with the extended ° d ONLN d“ ‰ ä – )e
TTxtPicRec ° d ONLN d‹ Â – Ò )F (as we do here). ° d ONLN dÓ ˛
(& 6• ° d ONLN d ˛ %
P )
?It is convenient that clipping regions are ignored between the ° d ONLN d/ ˝P è (&n TextBegin ° d ONLN d8 ˛è
DrawString ° d ONLN dÜ p⁄ )F on printers that don’t ° d ONLN dû %#œ (? CXsupport these comments. Unfortunately, this also means that text rotated this way can’t ° d ONLN dˆœ#⁄ (?Ìbe ° d ONLN d˘# %/◊ (K Cbclipped. If clipping of rotated text is required, you’ll have to do it entirely within PostScript. ° d ONLN d\; G (c 6• ° d ONLN d^; %GM )
@Due to the LaserWriter driver’s internal buffering of generated ° d ONLN dû;MG⁄ (ck PostScript code, the effect of ° d ONLN dΩG %SL (o C>ignoring clip regions may be propagated to preceding sections ° d ONLN d˚GLS⁄ (oj of your drawing instructions. ° d ONLN dT %` £ (| CWe recommend calling ° d ONLN d.T £` ∫ )~the ° d ONLN d2S ∫_F )FlushPostScriptState ° d ONLN dFTF`⁄ )å procedure described earlier ° d ONLN dca %m ì (â Cimmediately before the ° d ONLN dz` ìl “ )n TextBegin ° d ONLN dÉa “m )? comment. ° d ONLN dçz Ü (¢ 6• ° d ONLN dèz %Ü : )
The ° d ONLN dìy :Ö V )tJus ° d ONLN dóz VÜ é ) field in the ° d ONLN d•y éÖ ‘ )8
The ° d ONLN djœ <€ _ )tFlip ° d ONLN do– _‹ ü )# field in the ° d ONLN d}œ ü€  )@
TTxtPicRec ° d ONLN dᖠ‹¨ )F+ specifies horizontal or vertical flipping ° d ONLN d≤–¨‹⁄ )« about the ° d ONLN dº› %È ¨ ( C center point specified by the ° d ONLN d⁄‹ ¨Ë Ú )á
TextCenter ° d ONLN d‰› ÚÈ$ )F comment. ° d ONLN dÓˆ ( 6• ° d ONLN dˆ % : )
The ° d ONLN dÙı : Ä )
TextCenter ° d ONLN d˛ˆ ÄA )F* comment specifies the center of rotation ° d ONLN d (ˆA⁄ )¡ for any text enclosed within the ° d ONLN d I % d (+ C TextBegin ° d ONLN d R d )? and ° d ONLN d W ∞ )TextEnd ° d ONLN d ^ ∞ )1, calls, as an offset to the location of the ° d ONLN d ä⁄ )œcurrent point. The ° d ONLN d ù %â (7 CArotation is achieved by changing PostScript’s coordinate system. ° d ONLN d fiâ⁄ (7ß
A sequence of ° d ONLN d Ï %' ¥ (D CDrawString – MoveTo ° d ONLN d ˇ ¥(3 )è instructions is rotated ° d ONLN d
3(ò )as a whole until ° d ONLN d
)ò'… )eTextEnd ° d ONLN d
0 …(⁄ )1 is ° d ONLN d
4( %4 b (P C encountered. ° d ONLN d
AA M (i 6• ° d ONLN d
CA %Mm )
BSome versions of double-byte Kanji systems print Kanji characters ° d ONLN d
ÖAmM¢ (iã by calling ° d ONLN d
ê@¢L⁄ )5CopyBits ° d ONLN d
ôM %Yl (u CBinstead of calling standard text drawing routines. This means the ° d ONLN d
€MlY⁄ (uäcomments in the Text ° d ONLN d
Y %e … (Å C Rotation family cannot be used ° d ONLN d Y …e⁄ )§4with these fonts. Instead, use the Graphics Rotation ° d ONLN d De %q ˆ (ç C,comment family described later in this Note. ¡ 4¡˘
(÷ 68 ) of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇ J ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d < , ≈ ( H ZLine Layout Control
° d ONLN d 9 < E { * Comments: ,
Courier ° d ONLN d 8 Ñ D ÿ )H LineLayoutOn ° d ONLN d * 9 ÿ E fl )T, ° d ONLN d , 8 fl D: )
∫LΔ˛ )˛"pen position has changed since the ° d ONLN d
+« N”ª (Ô lAprevious text drawing instruction, or when picture comments like ° d ONLN d
lΔª“˙ (ÔŸ TextBegin ° d ONLN d
u«˙”˛ )?, ° d ONLN d
w” Nfl (¸ lTextEnd ° d ONLN d
~‘ ‡ Ü )1, ° d ONLN d
Ä” Üfl ” ) StringBegin ° d ONLN d
ã‘ ”‡ ⁄ )M, ° d ONLN d
ç” ⁄fl ) StringEnd ° d ONLN d
ñ‘‡j )? are encountered. ° d ONLN d
®Ï <¯ F ( Z2. ° d ONLN d
´Ï N¯‡ )XIt determines the width of the accumulated logical line of text, both on the screen and ° d ONLN d χ¯˛ (˛on the ° d ONLN d
¯ N> ( l5printer, and distributes the line layout error among ° d ONLN d ?¯>˛ )(the interword and intercharacter spacing ° d ONLN d h N ≤ (, lof the printed output. ° d ONLN d <) Q (E ZThe ° d ONLN d É Q( ¨ )
LineLayoutOff ° d ONLN d ê ¨)A )[ picture comment disables only ° d ONLN d Ø A)˛ )ï)the second step (distribution of the line ° d ONLN d Ÿ) <5i (Q ZAlayout error); the heuristic algorithm of accumulating text into ° d ONLN d )i5˛ (Qá a logically contiguous piece is ° d ONLN d :5 <A÷ (] ZXnot affected. Otherwise, if the character widths of the printer font are different from ° d ONLN d í5÷A˛ (]Ùthose of ° d ONLN d õA <MØ (i ZKthe screen font, and if the text contains exponents or indices, the latter ° d ONLN d ÊAØM˛ (iÕwould often be ° d ONLN d ıM <Y o (u Z
misplaced. ° d ONLN d
e <q Í *"The following code fragment shows ° d ONLN d
"e Íq˛ )Æ6a probably unexpected consequence of this behavior. We ° d ONLN d
Yq <} ’ (ô Z draw a line in two pieces three ° d ONLN d
yq ’}˛ )ô=times. A vertical line shows the starting pen position of the ° d ONLN d
∑~ <ä f (¶ Zsecond ° d ONLN d
æ} fâ ¨ )*
DrawString ° d ONLN d
»~ ¨äâ )F& call. The second line is enclosed by ° d ONLN d
Ó}â≠)›
LineLayoutOff ° d ONLN d
˚~‰äÌ )[ ° d ONLN d
¸~Ìä˛ ) and ° d ONLN d ä <ñ ê (≥ Z LineLayoutOn ° d ONLN d ã êó Í )T picture comments. ¡ X¡
(÷ Z&QD 10 - Picture Comments—The Real Deal (÷ˇ9 ) of 26 (Ï ZM.QD.PictComments ˇ h ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ) 4 § *# PROCEDURE ObserveLineLayout; ° d ONLN d = H @ * CONST ° d ONLN d & G R! *
5 testString1 = 'Whatever you like, preferably '; ° d ONLN d \ Q \0 *
8 testString2 = 'with spaces, long and short words'; ° d ONLN d ï [ f § *
fontName = 'New York'; ° d ONLN d ≤ e p | *
fontSize = 14; ° d ONLN d « o z Ω *
! x0 = 20; { starting point } ° d ONLN d È y Ñ ^ *
y0 = 40; ° d ONLN d ¯ É é Æ *
h = 30; { line height } ° d ONLN d ó ¢ 6 * VAR ° d ONLN d ° ¨ ê *
familyID: Integer; ° d ONLN d7 ´ ∂ ê *
w, y : Integer; ° d ONLN dP ø @ * BEGIN ° d ONLN dY … ‘ ¬ *
y := y + h; ° d ONLN dı € *' PicComment(LineLayoutOn, 0, NIL); ° d ONLN d-ˇ
‡ *
( { Back to the original behavior. } ° d ONLN dV | *
MoveTo(x0, y); ° d ONLN dk Æ *
DrawString(testString1); ° d ONLN dä ( ê *
MoveTo(x0 + w, y); ° d ONLN d£' 2 Æ *
DrawString(testString2); ° d ONLN d¬; F ; * END;
° d ONLN d R ^ Ï *.And this is (approximately) the output of the ° d ONLN d¯Q Ï]c )‘ObserveLineLayout ° d ONLN d Rc^Ç )w (with ° d ONLN dRÇ^⁄ ) LaserWriter driver ° d ONLN d#^ jS (Ü 6Dversion 7.1.1, and the default setting “Font Substitution enabled”): ¡ 4¡˘
*P10 )
of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇ∂ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / † Ç † å † å ° ñ ° ö √
J v hˇ
n . Uü Uü ° d ONLN dˇˇ ( V w@Whatever you like, preferably with spaces, long and short words n ° d ONLN dˇˇ *(aaa) † ó
< k ë
1 Y m i ¢ ˇˇˇˇˇˇˇˇ 8 † ç † å ° ñ ° ö √
q v èˇ n cò ° d ONLN dˇˇ *@Whatever you like, preferably with spaces, long and short words Q∞ ° d ONLN dˇˇ *(aaa) † ó
< k ë
1 Ä m ê ¢ ˇˇˇˇˇˇˇˇ 8 † ç ° ñ ° ö ˇ˚ ¥
] w l‚ G0 ° d ONLN dˇˇ ( i x?Whatever you like, preferably with spaces, long and short words † ó
LineLayoutOff ° d ONLN dW# ÷ )[# comment is active, demonstrates a ° d ONLN dz÷ ˛ )≥dramatic ° d ONLN dÉ <*~ (F Z?counterexample to the popular belief that this picture comment ° d ONLN d¬ ~*˛ (Fúis here to assure precise ° d ONLN d‹* <6, (R Z4positioning of text. It seems the opposite is true, ° d ONLN d*,6˛ )+and the LaserWriter driver has deliberately ° d ONLN d<7 <C t (_ Z ignored the ° d ONLN dH6 tB ÷ )8MoveTo(x0+w,y) ° d ONLN dV7 ÷Cƒ )b2 instruction! What we would have expected is this: † Ç † å † å ° ñ ° ö √
| vöˇ
n . Uü Uü ° d ONLN dˇˇ (à w@Whatever you like, preferably with spaces, long and short words n ° d ONLN dˇˇ *(aaa) † ó
n k√
1ã mõ ¢ ˇˇˇˇˇˇˇˇ 8 † ç † å ° ñ ° ö √
£ v¡ˇ n cò ° d ONLN dˇˇ *@Whatever you like, preferably with spaces, long and short words Q∞ ° d ONLN dˇˇ *(aaa) † ó
n k√
1≤ m¬ ¢ ˇˇˇˇˇˇˇˇ 8 † ç ° ñ ° ö ˇ˚ S
ê vü G0 ° d ONLN dˇˇ (ú w Whatever you like, preferably † ó ° ñ ° ö ˇ˚ ^
ê2üÒ .∞ ° d ONLN dˇˇ )º!with spaces, long and short words † ó
n k√
"x1 > † å 0p mø "q M æ oæ † ç † ç † É
IR
. ° d ONLN dâ± sΩ( (Ÿ ë Figure 2—Desired result of the ° d ONLN d®∞(ºê )µ
LineLayoutOff ° d ONLN dµ±êΩΔ )h comment ° d ONLN dæ… <’µ (Ò ZMThe attentive reader already knows the explanation. As mentioned earlier, we ° d ONLN d …µ’˛ (Ò”must break the ° d ONLN d÷ <‚) (˛ Z1LaserWriter driver’s heuristic line accumulation ° d ONLN dK÷)‚≠ )Ìalgorithm before drawing ° d ONLN dd’≠·˙ )Ñ testString2 ° d ONLN do÷˙‚˛ )M. ° d ONLN dq„ <Ô fi ( Z!Short of adequate documentation, ° d ONLN dí„ fiÔÄ )¢!developers have found out that a ° d ONLN d≥‚ÄÓ˛ )¢FlushGrafPortState ° d ONLN dΔ <¸ ë ( Zcall right after the ° d ONLN d€Ô ë˚ Û )UMoveTo(x0+w,y) ° d ONLN dÈ Û¸Õ )b2 instruction has the desired effect (see {••• (2) ° d ONLN dÕ¸˛ )⁄ •••} in the ° d ONLN d'¸ <r ($ ZFcode snippet given earlier). Unfortunately, it creates quite a lot of ° d ONLN dm¸r˛ ($ê overhead in the pictures, and ° d ONLN dã <â (1 ZJpenalizes all printer drivers that don’t need it. A better solution is to ° d ONLN d’ â± (1ßuse the ° d ONLN d›±˛ )( StringBegin ° d ONLN dÈ <" Q (> Zand ° d ONLN dÌ Q! ê ) StringEnd ° d ONLN dˆ ê"ù )?8 picture comments at the markers {••• (1) •••} and {••• ° d ONLN d.ù"˛ (>ª(2) •••} in the code ° d ONLN dC# </ ‡ (K Z#shown earlier. This indicates that ° d ONLN df" ‡.- )§ testString1 ° d ONLN dq#-/≈ )M! is to be considered a logically ° d ONLN dí#≈/˛ )ò independent ° d ONLN dû/ <; (W ZWtext entity, and must not be put together with any other pieces of text coming through ° d ONLN dı/;˛ (Wthe ° d ONLN d˘; <G t (d ZtextProc ° d ONLN d< tH‰ )8L bottleneck. The overhead of these comments is much smaller, and they don’t ° d ONLN dM<‰H˛ (daffect ° d ONLN dTH <T ∑ (p Z other printer drivers at all. ° d ONLN dra <m T *The ° d ONLN dv` Tl ƒ )ClientLineLayout ° d ONLN dÜa ƒm˛ )p; picture comment, supported by the (PostScript) LaserWriter ° d ONLN d¬m <yª (ï ZTdriver, has never been documented. Its effect is rather subtle and very specific to ° d ONLN d mªy˛ (ïŸthe PostScript ° d ONLN d %y <ÖÑ (° ZILaserWriter driver. Basically, it allows the application to redefine the ° d ONLN d nyÑÖ˛ (°¢character that absorbs the ° d ONLN d âÖ <ë [ (≠ Zmajor ° d ONLN d èÖ [ë˛ ) Wpart of the line layout error (usually the space character), and the percentages of the ¡ X¡
(÷ Z&QD 10 - Picture Comments—The Real Deal (÷˙11 )
of 26 (Ï ZM.QD.PictComments ˇ< ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) § * “major” and “minor” parts of ° d ONLN d § )⁄ )åAthe line layout error (usually 80 percent versus 20 percent). The ° d ONLN d _ ) 5! ( Q 6:“minor” part is distributed across intercharacter spacing. ° d ONLN d õ A MK *AOnly very ambitious page layout applications might be interested ° d ONLN d ‹ AK Mé ( iiin this functio ° d ONLN d Ï Aé Mô )Cna ° d ONLN d Ô Aô M⁄ ) lity; but then, ° d ONLN d ˇ M Y è ( u 6they should rather aim at ° d ONLN d M è Y⁄ )wDa more general scheme of line layout control that does not rely upon ° d ONLN d^ Y e › ( Å 6*this very driver-specific picture comment. ° d ONLN dâ r ~ 1 *The ,
*Some older printer drivers supporting the ° d ONLN d” Δ Î “F )Δ
LineLayoutOff ° d ONLN d‡ «F ”I )[ ° d ONLN d· «I ”⁄ ) picture comment are unable to ° d ONLN dˇ ‘ % ‡ ´ ( ¸ C correctly obey a subsequent ° d ONLN d ” ´ fl ˇ )Ü LineLayoutOn ° d ONLN d' ‘ ˇ ‡T )T picture comment. ° d ONLN d9 Ì ˘ ( 6• ° d ONLN d; Ì % ˘ d )
Don’t forget ° d ONLN dH Ì d ˘ ≤ )?that if you use ° d ONLN dX Ï ≤ ¯
)N
LineLayoutOff ° d ONLN de Ì
˘⁄ )[#, the burden of “WYSIWYG” is now on ° d ONLN dâ ˘ % ı (! C-your shoulders, and not the printer driver’s. ° d ONLN d∑ (: 6• ° d ONLN dπ % Á )
*A previous version of this Note said that ° d ONLN d„ Á l )¬setting the Font Manager’s ° d ONLN d˛l π )Ö FractEnable ° d ONLN d π ⁄ )M global ° d ONLN d %+ 1 (G Cto ° d ONLN d 1* M ) TRUE ° d ONLN d M+ ¬ ) implied the effect of the ° d ONLN d3 ¬* )u
LineLayoutOff ° d ONLN d@ +⁄ )[' picture comment. As it turned out, the ° d ONLN dh+ %7 ˙ (S C)statement was based on observations with ° d ONLN dë+ ˙7⁄ )’-a specific (older) version of the LaserWriter ° d ONLN dø8 %D (` C3driver, and is not true in general. The setting of ° d ONLN dÚ7C^ )Ï FractEnable ° d ONLN d˝8^D≥ )M does have some ° d ONLN d
8≥D⁄ )Umore or ° d ONLN dD %P ‰ (l C'less subtle effects on the line layout ° d ONLN d<D ‰P⁄ )ø0algorithm, however; and this is quite plausible. ° d ONLN dmQ %]* (y C0Similarly, the results of combining the picture ° d ONLN dùQ*]d (yH comments ° d ONLN d¶Pd\ø ):
LineLayoutOff ° d ONLN d≥Qø]⁄ )[ and ° d ONLN d∏] %i y (Ü C LineLayoutOn ° d ONLN dƒ^ yj º )T with calls to ° d ONLN d”] ºi )C
SpaceExtra ° d ONLN d›^j )F ( ° d ONLN dfl^ j^ ) Inside Macintosh ° d ONLN dÔ^^j⁄ )S Volume I, page 172) or ° d ONLN dj %v d (ì C CharExtra ° d ONLN dk dw p )? ( ° d ONLN dk pw Δ ) Inside Macintosh ° d ONLN d"k ΔwE )V Volume V, page 77) ° d ONLN d6kEw⁄ ) are sometimes unpredictable, ° d ONLN dSw %É Í (ü C+depending on the particular printer driver. ° d ONLN dè õ ∑ (∑ 6And Finally the Good News ° d ONLN dô® ¥ c *Given that the ° d ONLN d®® c¥ ß )Keffect of the ° d ONLN d∂ß ß≥ )D
LineLayoutOff ° d ONLN d√®¥ )[ and ° d ONLN d»ß ≥s ) LineLayoutOn ° d ONLN d‘®s¥⁄ )T comments does not ° d ONLN dÁ¥ ¿9 (‹ 6=require any changes in your printing code, you don’t have to ° d ONLN d$¥9¿⁄ (‹W!worry whether or not a particular ° d ONLN dF¿ à ä (Ë 6driver supports them. ° d ONLN d\¿ äÃ⁄ )r<They are useful mainly when you’re sure you want no external ° d ONLN dôà ÿ Ó (Ù 6+assistance in computing word and character ° d ONLN dƒÃ Óÿ⁄ )÷0spacing for full justification, or when you need ° d ONLN dıÿ ‰ b ( 6precise control ° d ONLN dÿ b‰⁄ )JJover the horizontal placement of words and characters (such as in forms or ° d ONLN dP‰ ( 63tabulated text) and understand how to achieve this.
° d ONLN dÑ ô *'String Delimitation
° d ONLN dô$ 0 W * Comments: ° d ONLN d£# `/ ≠ )H StringBegin ° d ONLN dÆ$ ≠0 ¥ )M, ° d ONLN d∞# ¥/ Û ) StringEnd ° d ONLN d∫< H 9 (d 6These ° d ONLN d¿< 9H⁄ )!Qcomments allow applications to specify the logical beginning and end of a string, ° d ONLN d I U (q 67possibly drawn with multiple calls to a QuickDraw text ° d ONLN d II Uö (q<drawing routine (such as ° d ONLN d bHöT“ )|DrawChar ° d ONLN d jI“U⁄ )8). ° d ONLN d mU a S (} 6 If this was ° d ONLN d yU Sa⁄ );Mtheir only raison d’être, they would have no relationship with the PostScript ° d ONLN d «a m x (â 6LaserWriter driver. ° d ONLN d €a xm⁄ )`IBut, as already let out in the preceding section on line layout, they are ° d ONLN d
%m y J (ï 6
important ° d ONLN d
/m Jy⁄ )2Pto notify the printer driver that it should consider the text coming through the ° d ONLN d
Äy Ö P (¢ 6textProc ° d ONLN d
àz PÜ ≥ )8 bottleneck between ° d ONLN d
úy ≥Ö )c StringBegin ° d ONLN d
ßz Ü )M and ° d ONLN d
¨yÖZ ) StringEnd ° d ONLN d
µzZÜ⁄ )? as an independent entity. ° d ONLN d
–Ü íH (Æ 6>Otherwise, the driver might continue to perform its heuristic ° d ONLN d ÜHí⁄ (Æf accumulation of text drawing ¡ 4¡˘
(÷ 612 )
of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇ∂ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d < ) Ò ( E Z$instructions for the same line, and ° d ONLN d $ Ò )˛ )µ5defeat your text positioning intentions. Indeed, both ,
Courier ° d ONLN d Z ) < 5 â ( R Z StringBegin ° d ONLN d e * â 6 † )M and ° d ONLN d j ) † 5 fl ) StringEnd ° d ONLN d s * fl 6ä )?& trigger the generation of PostScript ° d ONLN d ô *ä 6˛ )´instructions for drawing ° d ONLN d ≤ 6 < B u ( ^ Zthe text that ° d ONLN d ¿ 6 u B˛ )9Uhas been accumulated in a line layout buffer, and reinitialize the internal variables ° d ONLN d B < N N ( j Zfor ° d ONLN d B N N˛ )Uline layout computations. In other words, you need these picture comments to turn the ° d ONLN dp N < ZG ( v Z9LaserWriter driver’s line layout behavior completely off.
° d ONLN d™ r < Å Ë *'Polygon Comment Family
° d ONLN d¡ é < ö { * Comments: ° d ONLN dÀ ç Ñ ô √ )H PolyBegin ° d ONLN d‘ é √ ö )?, ° d ONLN d÷ ç ô ˚ )PolyEnd ° d ONLN d› é ˚ ö )1, ° d ONLN dfl ç ôA ) PolyClose ° d ONLN dË éA öH )?, ° d ONLN dÍ çH ôé )
PolySmooth ° d ONLN dÙ éé öï )F, ° d ONLN dˆ çï ô€ )
PolyIgnore ° d ONLN d ¶ < ≤z ( Œ ZEPostScript has the built-in capability of drawing cubic Bézier curve ° d ONLN dF ¶z ≤Õ ( Œòsections (see the ° d ONLN dX ¶Õ ≤˛ )S
PostScript ° d ONLN dc ≤ < æ m ( ⁄ Z Language ° d ONLN dl ≤ m æ À )1Reference Manual, ° d ONLN d~ ≤ À æ˛ )^=Second Edition, page 393). This is convenient for “smoothing” ° d ONLN dº æ < : ( Ê Z2of polygons. The polygon-related picture comments ° d ONLN dÓ æ: ˛ )˛'have been provided to give applications ° d ONLN d < ÷Ä ( Ú ZGeasy access to this PostScript feature, with provision for including a ° d ONLN d] Ä ÷˛ ( ÚûQuickDraw approximation ° d ONLN du ÷ < ‚ x ( ˛ Z
of the curve. ° d ONLN dÉ Ó < ˙P *8Schematically, the polygon comments are used as follows: ° d ONLN dΩ ` õ +$ PolyBegin ° d ONLN dΔ õ Ã );Comment; ° d ONLN d–u )y{ Put the PostScript ° d ONLN dÂu˛ )adriver into “polygon mode.” ° d ONLN d < B (: Z} ° d ONLN d `* Ω +$ ClipRect(zeroRect); ° d ONLN d *≤ )ê&{ Hide the following from QuickDraw. } ° d ONLN dA* `6 ö (R ~ PolyClose ° d ONLN dJ* ö6 À ):Comment; ° d ONLN dT*6Ó )z.{ Optionally, if “closed” smoothing desired. } ° d ONLN dÑ6 `B • (^ ~
PolySmooth ° d ONLN dé6 •B ÷ )EComment; ° d ONLN dó6 Bµ )K+{ Tell the driver to draw a Bézier curve. } ° d ONLN dƒB `N • (j ~ DrawPolygon; ° d ONLN d“B N¯ )ê7{ Invisible for QuickDraw; PostScript output = curve. } ° d ONLN d N `Z ü (v ~
PolyIgnore ° d ONLN dN üZ – )?Comment; ° d ONLN d N ZÌ )Q6{ The driver will ignore the following line drawing. } ° d ONLN dVZ `f … (Ç ~SetClip(origClipRgn); ° d ONLN dlZ fï )ê"{ Make it visible for QuickDraw. } ° d ONLN dêf `r µ (é ~DrawQDPolygon; ° d ONLN d†f rÚ )ê4{ Usually, a QuickDraw approximation of the curve. } ° d ONLN d÷r `~ ê (ö ~PolyEnd ° d ONLN d›r ê~ ¡ )0Comment; ° d ONLN dÁr ~» )`,{ PostScript driver resumes standard mode. } ° d ONLN dä <ñ ∑ (≤ ZA piece of sample code is ° d ONLN d.ä ∑ñ˛ ){Asometimes worth more than one or two pictures; below, you’ll find ° d ONLN dpñ <¢å (æ ZEboth. For clarity and completeness of the exposition, we provide the ° d ONLN dµñå¢˛ (æ™coordinate definition of ° d ONLN dŒ£ <Ø ‡ (À Z the polygons through arrays of ° d ONLN dÌ¢ ‡Æ )§Point ° d ONLN dÚ£Ø_ )#s, initialized in a ° d ONLN d£_Øú )\ preliminary ° d ONLN d¢úÆ˛ )=DefineVertices ° d ONLN d!∞ <º ‚ (ÿ Z procedure. You can enclose the ° d ONLN d@Ø ‚ª/ )¶ PolygonDemo ° d ONLN dK∞/º5 )M ° d ONLN dL∞5ºô )procedure between ° d ONLN d^ØôªÊ )d OpenPicture ° d ONLN di∞ʺ˛ )M and ° d ONLN dnº <» ê ( Z ClosePicture ° d ONLN dzΩ ê…t )T+ calls to create a picture containing both ° d ONLN d•Ωt…˛ )‰QuickDraw and PostScript ° d ONLN dæ… <’Ê (Ò Z\representations (see Figures 3 and 4), or you can use it as is when a printing page is open.
° d ONLN d· <Ï ë *USES PicComments; ° d ONLN d-Î <ˆ≥ *
K{ See Appendix of this Note for the definition of the TPolyRec structure. } ° d ONLN dyˇ <
d * CONST ° d ONLN dÇ <; *
3 kN = 4; { number of vertices for PostScript } ° d ONLN d∂ < | *
@ kM = 6; { number of vertices for QuickDraw approximation } ° d ONLN d˜' <2 _ * TYPE ° d ONLN dˇ1 <<| *
@ PointArray = array[0..0] of Point; { range checking OFF } ° d ONLN d @; <F Ê *
" PointArrayPtr = ^PointArray; ° d ONLN d cO <Z1 *1PROCEDURE DefineVertices(VAR p,q: PointArrayPtr); ° d ONLN d ïc <n d * CONST ° d ONLN d ûm <x á *
cx = 280; ° d ONLN d Æw <Ç á *
cy = 280; ° d ONLN d æÅ <å á *
r0 = 200; ¡ X¡
*.&QD 10 - Picture Comments—The Real Deal (÷˙13 )
of 26 (Ï ZM.QD.PictComments ˇ“ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ( @ * BEGIN ° d ONLN d ' 2q *
E { The array p^ contains the control points for the Bézier curve: } ° d ONLN d O 1 < Æ *
SetPt(p^[0],cx + r0,cy); ° d ONLN d n ; F Æ *
SetPt(p^[1],cx,cy + r0); ° d ONLN d ç E P Æ *
SetPt(p^[2],cx - r0,cy); ° d ONLN d ¨ O Z Æ *
SetPt(p^[3],cx,cy - r0); ° d ONLN d À Y d Å *
p^[4] := p^[0]; ° d ONLN d · c nô *
M { q^ contains the points for a crude polygon approximation of the curve: } ° d ONLN d/ m x Å *
q^[0] := p^[0]; ° d ONLN dE w Ç+ *
7 SetPt(q^[1],cx,cy + round(0.7 * (p^[1].v - cy))); ° d ONLN d} Å å{ *
G SetPt(q^[2],(p^[1].h + p^[2].h) DIV 2,(p^[1].v + p^[2].v) DIV 2); ° d ONLN d≈ ã ñ+ *
? IF (p = NIL) OR (q = NIL) THEN DebugStr('NewPtr failed'); ° d ONLN d€I T ö *
DefineVertices(p,q); ° d ONLN dˆ] hî *L PenNormal; { First show the standard QuickDraw polygon. } ° d ONLN dCg r Æ *
MoveTo(p^[0].h,p^[0].v); ° d ONLN dbq | *
2 FOR i := 1 TO kN DO LineTo(p^[i].h,p^[i].v); ° d ONLN dôÖ êî *L PenSize(2,2); { Now show the same polygon "smoothed." } ° d ONLN dÊè ö w *
PenPat(gray); ° d ONLN d˙ô §è *
K { First, the PostScript representation, clipped off from QuickDraw: } ° d ONLN dF£ Æ] *
A aPolyVerbH:= TPolyVerbHdl(NewHandle(SizeOf(TPolyVerbRec))); ° d ONLN dà≠ ∏ Æ *
IF aPolyVerbH<> NIL THEN ° d ONLN dß∑ ¬è *
K WITH aPolyRecH^^ DO BEGIN { ••• See comment 1, below. ••• } ° d ONLN dÛ¡ Ã ≥ *
fPolyFrame := TRUE; ° d ONLN dÀ ÷ ∏ *
fPolyFill := FALSE; ° d ONLN d4’ ‡è *
K fPolyClose := FALSE; { Compare with the result for TRUE ! } ° d ONLN dÄfl Í ê *
f3 := FALSE; ° d ONLN dôÈ Ù ê *
f4 := FALSE; ° d ONLN d≤Û ˛ ê *
f5 := FALSE; ° d ONLN dÀ˝ ê *
f6 := FALSE; ° d ONLN d‰ ê *
f7 := FALSE; ° d ONLN d˝ Y *
END; ° d ONLN d &è *
K MoveTo(p^[0].h,p^[0].v); { ••• See comment 2, below. ••• } ° d ONLN dW% 0 ¬ *
" PicComment(PolyBegin,0,NIL); ° d ONLN dz/ :è *
K { PicComment(PolyClose,0,NIL); <<< Only if fPolyClose = TRUE, above! } ° d ONLN dΔ9 Dq *
E PicComment(PolySmooth,SizeOf(TPolyVerbRec),Handle(aPolyVerbH)); ° d ONLN d C N ê *
clipRgn := NewRgn; ° d ONLN d%M X ã *
GetClip(clipRgn); ° d ONLN d=W b ï *
ClipRect(zeroRect); ° d ONLN dWa l *
2 FOR i := 1 TO kN DO LineTo(p^[i].h,p^[i].v); ° d ONLN däu Äî *L { Next, the -crude- QuickDraw approximation of the smoothed polygon, } ° d ONLN d◊ ä5 *
9 { invisible for PostScript because of PolyIgnore: } ° d ONLN d â î ã *
SetClip(clipRgn); ¡ 4¡˘
*&14 )
of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇ§ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d < ( Î ( D Z# PicComment(PolyIgnore,0,NIL); ° d ONLN d $ ' < 2∏ *
L polyRgn := NewRgn; { ••• See comment 3, below. ••• } ° d ONLN d q 1 < < Ç *
OpenRgn; ° d ONLN d Ä ; < F “ *
MoveTo(q^[0].h,q^[0].v); ° d ONLN d ü E < P6 *
2 FOR i := 1 TO kM DO LineTo(q^[i].h,q^[i].v); ° d ONLN d “ O < Z ¥ *
CloseRgn(polyRgn); ° d ONLN d Î Y < d∏ *
L FrameRgn(polyRgn); { Or FillRgn, if fPolyFill above is TRUE. } ° d ONLN d8 c < n ‹ *
PicComment(PolyEnd,0,NIL); ° d ONLN dY w < Ç ˇ *' DisposHandle(Handle(aPolyVerbH)); ° d ONLN dÅ Å < å æ *
DisposeRgn(polyRgn); ° d ONLN dú ã < ñ ¥ *
DisposPtr(Ptr(p)); ° d ONLN dµ ï < † ¥ *
DisposPtr(Ptr(q)); ° d ONLN dŒ ü < ™ _ *
END; † Ç
‘ Z£+
0Ià:µú9 "ü ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å † å ° d `drw2 " / Ì ˙-8@“»Âí ˇˇˇˇˇˇ † EÄ "-8 ï à ˙Âí Ì“» ï à /@ "-8 ï SPC SPC " ’ ¡ † æ q ’ [†& ’ ¡;&† ¡; [ ’ ¡ † ø SPC SPC # † † † •
Ñ
≥ , ≥ , ˇˇˇˇˇˇˇˇ #ef #õe #öõ #fö † ° ° d Xdrw2 I L á ˜ ™™ ˇˇˇˇˇˇ Œ , á ˜™™ I ô@ Q€n e¿ á L ™U™U™U™U # # ° d
ONLN f @ # SPC SPC # ™U™U™U™U # # ° d
ONLN f @ # † † "9#°¬ #Õ #Ê5 † ° ° d Xdrw2 à K « ˘UU ™™ ˇˇˇˇˇˇ } , àUU ˘™™ « ôôö æ 1 e33 àUU K # # ° d
ONLN f @ # SPC SPC # ™U™U™U™U # # ° d
ONLN f @ # † † ":%†? #À˜ #Ê † ° † ç † å ° d Xdrw2 BP â¸UU UU™™ ˇˇˇˇˇˇ } âUU¸™™ BUUö«Ë WªT q à\YP # # ° d
fPolyClose ° d ONLN d§⁄ ¨Ê( )F flag is redundant with ° d ONLN dº⁄(Ê= )|the ° d ONLN d¿Ÿ=Â| ) PolyClose ° d ONLN d…⁄|Ê˛ )? picture comment, but is ° d ONLN d‚Ê NÚË ( lVincluded for the convenience of the LaserWriter driver. It is often misunderstood. It ° d ONLN d8ÊËÚ˛ (does ° d ONLN d=Ú N˛ ` ( lnot ° d ONLN d@Ú `˛ ˙ ) mean the polygon is being ° d ONLN d[Ú ˙˛˛ )ö1closed automatically, such as with the PostScript ° d ONLN dç˛ N
ç (' l closepath ° d ONLN dñˇ ç ç )?7 operator; instead, it affects the shape of the smooth ° d ONLN dÕˇç ˛ ('´curve. Figure 4 shows ° d ONLN d„ N ñ (4 lthe result for ° d ONLN dÚ ñ! )HfPolyClose = FALSE; ° d ONLN d !É )ã the start and end ° d ONLN d ɲ )bpoint of the polygon is ° d ONLN d0 N% ‡ (A l distinguished. In the case of ° d ONLN dN ‡$[ )ífPolyClose = TRUE ° d ONLN d_[%d ){, ° d ONLN dad%˛ ) all vertices of the polygon are ° d ONLN dÅ% N1÷ (M lVtreated in the same manner, and the resulting curve resembles a circle (in this case). ° d ONLN dÿ> <J F (f Z2. ° d ONLN d€> NJ ∫ )The anonymous fields ° d ONLN d= ∫I ‰ )lf3..f7 ° d ONLN dˆ> ‰J¬ )*2 are reserved and should be set to zero (that is, ° d ONLN d(=¬I )fiFALSE ° d ONLN d->ÂJÌ )#). ° d ONLN d0W <c F ( Z3. ° d ONLN d3W Nc ¡ )The polygon is drawn ° d ONLN dHW ¡cÄ )s%at the current pen location when the ° d ONLN dmVÄbø )ø PolyBegin ° d ONLN dvWøc˛ )? comment is ° d ONLN dÇc No y (ã l received. ° d ONLN dç{ <á F (£ Z4. ° d ONLN dê{ Ná ¨ )In general (and in ° d ONLN d£{ ¨á" )^this example), you do ° d ONLN dπ{"á4 )vnot ° d ONLN dº{4Რ)( need to open a region, collect the line ° d ONLN dÂà NîQ (∞ l5segments in the region, and draw the polygon through ° d ONLN dáQìâ (∞oFrameRgn ° d ONLN d"àâîê )8. ° d ONLN d$àêî˛ )It is demonstrated here ¡ X¡
(÷ Z&QD 10 - Picture Comments—The Real Deal (÷˙15 )
of 26 (Ï ZM.QD.PictComments ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø ° ¿ :0.500 userdict /_cv known {_cv begin stg end}{pop}ifelse
° ¿ :0.500 userdict /_cv known {_cv begin stg end}{pop}ifelse
° ¿ :0.500 userdict /_cv known {_cv begin stg end}{pop}ifelse
° ¿ :0.500 userdict /_cv known {_cv begin stg end}{pop}ifelse
° ¿ :0.500 userdict /_cv known {_cv begin stg end}{pop}ifelse
° ¿ :0.500 userdict /_cv known {_cv begin stg end}{pop}ifelse
° ¿ :0.500 userdict /_cv known {_cv begin stg end}{pop}ifelse
° ¿ :0.500 userdict /_cv known {_cv begin stg end}{pop}ifelse
⁄ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d * ) B +only ° d ONLN d B )⁄ )Tto prepare you for situations where you want to fill the polygon with a pattern. You ° d ONLN d Z * * 6 O ( R Hcannot ° d ONLN d ` * O 6 w )% open a ° d ONLN d h * w 6 Œ )(polygon and use ,
Courier ° d ONLN d x ) Œ 5 )WFillPoly ° d ONLN d Ä * 6⁄ )8*, because the PostScript driver “owns” the ° d ONLN d ´ 6 * Bü ( ^ HHpolygon concept at this point and captures—and ignores—all line drawing ° d ONLN d Û 6ü B⁄ ( ^Ω between the ° d ONLN d ˇ B * N p ( k H
PolyIgnore ° d ONLN d C p O á )F and ° d ONLN d B á N ∏ )PolyEnd ° d ONLN d C ∏ O≠ )12 comment. Regions do not interfere with polygons, ° d ONLN dG C≠ O⁄ )ıhowever, ° d ONLN dP O * [ ( w H5and can be used to paint or fill the polygonal shape. ° d ONLN dá g s D ( è 6Caveats ° d ONLN dè ã- *9PostScript Level 1 has problems with very large polygons ° d ONLN d» - ã⁄ ( ßK"(more than about 1000 points). The ° d ONLN dÎ ã ój ( ≥ 6Gworkaround is to subdivide the large polygon into several smaller ones. ° d ONLN d3 £ Ø / *You ° d ONLN d7 £ / Ø⁄ )Tcannot combine the polygon picture comments with other comments such as the rotation ° d ONLN då ∞ º i ( ÿ 6comments or the ° d ONLN dú Ø i ª Ø )Q
DashedLine ° d ONLN d¶ ∞ Ø ºß )F2 comment. It’s just another limitation—no comment.
° d ONLN d⁄ ‘ „ p ( ˇ 6 Dashed Lines
° d ONLN dÁ ¸ W * Comments: ° d ONLN dÒ Ô ` ˚ ¶ )H
DashedLine ° d ONLN d˚ ¶ ¸ ≠ )F, ° d ONLN d˝ Ô ≠ ˚ Û )
DashedStop ° d ONLN d ≥ (0 6XPostScript allows applications to draw precisely dashed lines with a given dash pattern ° d ONLN d`≥⁄ (0—in every ° d ONLN di ! k (= 6direction (see the ° d ONLN d| k ú )Ssetdash ° d ONLN dÉ ú! Õ )1 operator, ° d ONLN dé Õ!é )1&PostScript Language Reference Manual, ° d ONLN d¥é!¥ )¡Second ° d ONLN dª¥!⁄ )&Edition, ° d ONLN dƒ! - (I 63page 500). The QuickDraw ersatz of setting the pen ° d ONLN d˜!-⁄ )ˆ*pattern appears to be awkward at best; the ° d ONLN d"- 9å (U 6Hresult depends very much on the direction of the line. Coding correctly ° d ONLN dj-å9⁄ (U™dashed lines in ° d ONLN dz: F (b 6 QuickDraw is quite a hassle and ° d ONLN dö: F{ )≤ rather clumsy. This is why the ° d ONLN dπ9{E¡ )±
DashedLine ° d ONLN d√:¡F⁄ )F and ° d ONLN d»F R ^ (o 6
important ° d ONLN d)S J_⁄ )2Kand used frequently. Applications can take advantage of these comments when ° d ONLN du_ k ´ (á 6!printing to a PostScript printer. ° d ONLN dóx Ñ . *The ° d ONLN dõw .É t )
not currently ° d ONLN d˝´ ∑ (” 69supported by the LaserWriter driver. It should be set to ° d ONLN d6™ ∂& (”=0 ° d ONLN d7´&∑≤ ) in case support for centering ° d ONLN dV´≤∑⁄ )åis added ° d ONLN d_∑ √ U (fl 6in the future. ° d ONLN dn– ‹î *MUnlike the picture comments for text rotation or even polygon smoothing, the ° d ONLN dªœî€⁄ (¯≤
DashedLine ° d ONLN dΔ‹ Ë å ( 6picture comment should ° d ONLN d›‹ åË û )tnot ° d ONLN d‡‹ ûËz ). be supported by a non-PostScript driver. The ° d ONLN d‹zË⁄ )‹only way to include ° d ONLN d"È ı ¨ ( 6 representations of dashed lines ° d ONLN dBÈ ¨ıA )î with and without usage of the ° d ONLN d`ËAÙá )ï
DashedLine ° d ONLN djÈáı⁄ )F picture comment ° d ONLN d{ˆ 1 ( 6is to ° d ONLN dň 1 Û )&make the following assumption: If the ° d ONLN dßı Û9 )¬
DashedLine ° d ONLN d±ˆ9⁄ )F comment is supported, then the ° d ONLN d— E (+ 6 printer is ° d ONLN d‹ E — )- a PostScript printer, and the ° d ONLN d˙ —ú )å PostScriptBegin/PostScriptEnd ° d ONLN d ú⁄ )À bracket may ° d ONLN d $ p (7 6Fbe used to hide the QuickDraw imaging from the printer. Remember that ° d ONLN d jp⁄ (7énon-PostScript printer ° d ONLN d Å ( h (D 6
drivers must
° d ONLN d é h( z )Pnot ° d ONLN d ë z(S )! ignore QuickDraw imaging within ° d ONLN d ≤S'º )ŸPostScriptBegin ° d ONLN d ¡ º(⁄ )i and ° d ONLN d Δ( 4 s (Q 6
PostScriptEnd ° d ONLN d ”) s5 w )[! ° d ONLN d ’B N Ê (j 6+But we still need a trick to hide the line ° d ONLN d
B ÊNà )Œ drawing instructions within the ° d ONLN d
AàMŒ )¢
DashedLine ° d ONLN d
*BŒN⁄ )F – ° d ONLN d
-N Z ^ (w 6
DashedStop ° d ONLN d
7O ^[√ )FG bracket from QuickDraw. Here comes the “magic pen mode” to our rescue: ¡ 4¡˘
(÷ 616 )
of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇ$ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d < ( õ ( D ZPROCEDURE DashDemo; ° d ONLN d 1 < < d * CONST ° d ONLN d ; < F' *
/ magicPen = 23; { the infamous penMode ! } ° d ONLN d M E < P á *
cx = 280; ° d ONLN d ] O < Z á *
cy = 280; ° d ONLN d m Y < d á *
r0 = 200; ° d ONLN d } m < x Z * VAR ° d ONLN d Ñ w < Ç “ *
> - round(r0 * sin(i * 20 * rad)), dashHdl); ° d ONLN d¶È <Ù n *
END; ° d ONLN d±Û <˛ ˙ *
& PicComment(PostScriptEnd,0,NIL); ° d ONLN dÿ˝ < _ *
END;
° d ONLN d‡ < ë *By the way: The ° d ONLN d ë Â )U DashedQDLine ° d ONLN d¸ Â ˛ )T; procedure is intentionally missing. It’s not precisely the ° d ONLN d8 <,¿ (H ZWsubject of this Note, and thus, again, is left as a spare-time exercise for the reader. ° d ONLN dê8 <D b *Caveat ° d ONLN dóP <\Z *<As mentioned earlier, the current version of the PostScript ° d ONLN d”PZ\˛ (xx LaserWriter driver produces poor ° d ONLN dÙ] <i å (Ö Zresults when the ° d ONLN d\ åh “ )P
DashedLine ° d ONLN d] “i‡ )F: picture comment is applied to polygons. Just don’t do it! ¡ X¡
(÷ Z&QD 10 - Picture Comments—The Real Deal (÷˙17 )
of 26 (Ï ZM.QD.PictComments ˇR ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d , ¨ *Fractional Line Width
° d ONLN d 8 D Q *Comment: ° d ONLN d 8 ` D ° )H SetLineWidth ° d ONLN d , P \ß ( x 6MQuickDraw’s design is based on a fixed 72-dpi resolution. Even when printing ° d ONLN d y Pß \÷ ( x≈ to a high ° d ONLN d Ç P÷ \⁄ )/- ° d ONLN d É \ h É ( Ñ 6resolution device, the ° d ONLN d ö \ É h⁄ )kEPrinting Manager presents the printing grafPort, corresponding to the ° d ONLN d ‡ h t j ( ê 6printable area of ° d ONLN d Ú h j t⁄ )RHthe page, in the integer-valued QuickDraw coordinate system with 72 dpi. ° d ONLN d; u Å | ( ù 6Applications can use ,
Courier ° d ONLN dP t | Ä ª )d PrGeneral ° d ONLN dY u ª Å È )?
PicComment ° d ONLN dú À— ◊⁄ )F’s ° d ONLN dü ◊ „ ( ˇ 66data handle, the vertical coordinate representing the ° d ONLN d’ ◊ „⁄ )Ù*denominator, and the horizontal coordinate ° d ONLN d „ Ô ¢ ( 6 the numerator of the fraction. ° d ONLN d ˚ — *aUnfortunately, it is not implemented in all high-resolution QuickDraw printers; and if it is (as ° d ONLN dÄ ˚—⁄ (#Ôin ° d ONLN dÉ Û (/ 6/the LaserWriter SC), it works differently than ° d ONLN d≤ Û⁄ )€1in PostScript printer drivers. Moreover, there is ° d ONLN d‰ F (< 6>no possibility to include alternative imaging instructions in ° d ONLN d"F a (<dcase ° d ONLN d'a µ ) SetLineWidth ° d ONLN d3µ ⁄ )T is not ° d ONLN d; , á (H 6supported. While this ° d ONLN dQ á,⁄ )oBis not much of a loss for hairlines, it prevents us from using the ° d ONLN dî- 9 ≥ (U 6 comment for fractional widths > ° d ONLN d¥- ≥9ï )õ/1, where the alternative would be to include a ° d ONLN d„,ï8Δ )‚PenSize ° d ONLN dÍ-Δ9⁄ )1 call ° d ONLN d9 E¶ (a 6Swith rounded arguments. Another drawback may be that, allegedly, there are plotter ° d ONLN dC9¶E⁄ (aƒ drivers out ° d ONLN dOE Qú (m 6Sthere that abuse this comment to set the pen color—clearly an unpleasant situation. ° d ONLN d£^ j  *,The difference in the implementation of the ° d ONLN dœ] Âi9 )Õ SetLineWidth ° d ONLN d€^9j⁄ )T comment between the PostScript ° d ONLN d˚k w? (ì 6=LaserWriter driver and the LaserWriter SC appears as soon as ° d ONLN d8j?vì (ì] SetLineWidth ° d ONLN dDkìw∫ )T is used ° d ONLN dMk∫w⁄ )'for the ° d ONLN dUw É (ü 65second time. The PostScript driver keeps an internal ° d ONLN däwÉ⁄ )˘/line scaling factor; this factor is initialized ° d ONLN d∫Ñ ê6 (¨ 69to 1.0 when a job is started. Each number passed through ° d ONLN dÛÉ6èä (¨T SetLineWidth ° d ONLN dˇÑäêö )T is ° d ONLN dÑöê⁄ )
END; ° d ONLN d ” < fi ¥ * PROCEDURE LineWidthDemo; ° d ONLN d Á < Ú d * CONST ° d ONLN d( Ò < ¸ Î *
# y0 = 50; { topleft of demo } ° d ONLN dL ˚ < Ç *
x0 = 50; ° d ONLN d[ <" *
. d0 = 440; { length of horizontal lines } ° d ONLN dä < *
* e0 = 5; { distance between lines } ° d ONLN dµ <$ Î *
# kN = 5; { number of lines } ° d ONLN dŸ# <. Z *
VAR ° d ONLN d‡- <8h *
< oldWidth,newWidth: TLineWidth; { actually a "Point" } ° d ONLN d 7 <B • *
i,j,y: Integer; ° d ONLN d3K <V d * BEGIN ° d ONLN d<U <` å *
PenNormal; ° d ONLN dM_ <j Ç *
y := y0; ° d ONLN d\i <tÜ *
B SetPt(oldWidth,1,1); { initial linewidth = 1.0 } ° d ONLN düs <~ “ *
FOR i := 1 TO 5 DO BEGIN ° d ONLN dæ} <à Õ *
SetPt(newWidth,4,i); ° d ONLN d‹á <íÜ *
B { want to set it to i/4 = 0.25, 0.50, 0.75 ... } ° d ONLN d ë <ú *
, SetNewLineWidth(oldWidth,newWidth); ° d ONLN dLõ <¶ Ø *
MoveTo(x0, y); ° d ONLN dd• <∞ • *
Line(d0, 0); ° d ONLN dzØ <∫ • *
y := y + e0; ° d ONLN dêπ <ƒ “ *
oldWidth := newWidth; ° d ONLN dØ√ <Œ n *
END; ° d ONLN d∫Õ <ÿ _ *
END;
° d ONLN d¬„ <Ô @ *• ° d ONLN d√„ @Ô ª )A Slight Imperfection ° d ONLN dŸÔ <˚ A ( Z• ° d ONLN d€˚ < A * • ° d ONLN d‹˚ A Δ )If you experiment with the ° d ONLN d˜˚ Δ˛ )Ö=above code and draw a whole series of hairlines, you will see ° d ONLN d5 < É (0 Z(depending on ° d ONLN dC É ≈ )Gthe values of ° d ONLN dQ ≈ ” )Be0 ° d ONLN dS ” Ï ) and ° d ONLN dX Ï ˙ )kN ° d ONLN dZ ˙˛ )8) that certain lines appear thicker than they should be. ° d ONLN dì < Ì (< ZXThis is due to rasterization effects in PostScript’s scan conversion algorithm when the ° d ONLN dÎÌ ˛ (< line ° d ONLN d <,L (H Z<width is close to the device pixel size. In many cases, the ° d ONLN d, L,˛ (Hj&PostScript LaserWriter driver tries to ° d ONLN dS, <8^ (T Z3compensate for this by rounding coordinates to the ° d ONLN dÜ,^8˛ (T| 300-dpi grid. If you include ° d ONLN d£8 <D ê (a Z SetLineWidth ° d ONLN dØ9 êE ∑ )T (or, by ° d ONLN d∏9 ∑E  )' the way, ° d ONLN d¡8 ÂD+ ).
(÷ Z&QD 10 - Picture Comments—The Real Deal (÷˙19 )
of 26 (Ï ZM.QD.PictComments ˇ
◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d , ê *Graphics Rotation
° d ONLN d 9 E W * Comments: ,
Courier ° d ONLN d 8 ` D ≠ )H RotateBegin ° d ONLN d ' 9 ≠ E ¥ )M, ° d ONLN d ) 8 ¥ D ) RotateCenter ° d ONLN d 5 9 E )T, ° d ONLN d 7 8 DN ) RotateEnd ° d ONLN d A Q ] õ ( y 6Like the picture comments ° d ONLN d [ Q õ ]⁄ )ÉBdiscussed earlier in this Note in the section “Text Rotation,” the ° d ONLN d û ] i à ( Ö 6#graphics rotation picture comments ° d ONLN d ¡ ] à i⁄ )¥1provide a method of rotating QuickDraw objects on ° d ONLN d Û i uª ( ë 6YPostScript devices. Instead of having QuickDraw perform the rotation, the printer driver ° d ONLN dL iª u⁄ ( ëŸrotates ° d ONLN dT v Ç Ì ( û 6/the entire PostScript coordinate space so that ° d ONLN dÉ v Ì Ç) )’
PostScript ° d ONLN dD∂!π ); ° d ONLN dEπ!⁄ )drivers ° d ONLN dM! - À (I 6#implement these comments. The only ° d ONLN dp! À-⁄ )≥7way to hide the QuickDraw substitute from the driver is ° d ONLN d®. : n (V 6to surround it by ° d ONLN d∫- n9 ◊ )VPostScriptBegin ° d ONLN d…. ◊: € )i ° d ONLN d . €: Ò )and ° d ONLN dŒ- Ò9L )
PostScriptEnd ° d ONLN d€.L:⁄ )[ comments; and, similarly to ° d ONLN d¯; G ) (c 6the ° d ONLN d¸: )F o )
DashedLine ° d ONLN d; oG µ )F
comment, we ° d ONLN d; µG⁄ )F;need to use the “magic pen mode” (23) to hide the unrotated ° d ONLN dOH T n (p 6drawing between ° d ONLN d_G nS ª )V RotateBegin ° d ONLN djH ªT ‘ )M and ° d ONLN doG ‘S ) RotateEnd ° d ONLN dxHTÜ )? from QuickDraw. The ° d ONLN dçHÜT⁄ )sfollowing sample ° d ONLN dûT ` m (| 6demonstrates this:
° d ONLN d±l wI *=PROCEDURE QDRotatedRect(r: Rect; ctr: Point; angle: Integer); ° d ONLN dÔv Å @ *
BEGIN ° d ONLN d¯Ä ãN *
> { An exercise again - this one is easy ... } ° d ONLN d7ä ïN *
> { Rotates the four points of the rectangle by "angle" } ° d ONLN dvî üN *
A PicComment(RotateBegin,SizeOf(TRotationRec),Handle(rInfo)); ° d ONLN d∂ Ω < » *$ oldPenMode := thePort^.pnMode; ° d ONLN d€ « < “ ¥ *
PenMode(magicPen); ° d ONLN dÙ — < ‹ õ *
FrameRect(r); ° d ONLN d € < Ê æ *
PenMode(oldPenMode); ° d ONLN d# Ô < ˙ Ê *" PicComment(RotateEnd,0,NIL); ° d ONLN dF < Î *# DisposeHandle(Handle(rInfo)); ° d ONLN dj
< ı *
% DisposeHandle(Handle(rCenter)); ° d ONLN dê <" _ *
END; ° d ONLN dò+ <6 • *PROCEDURE RotateDemo; ° d ONLN dÆ? <J d * CONST ° d ONLN d∑I <T ë *
angle = 30; ° d ONLN d…] <h Z * VAR ° d ONLN d–g <r • *
spinRect: Rect; ° d ONLN dÊq <| õ *
delta: Point; ° d ONLN d˙Ö <ê d * BEGIN ° d ONLN dè <ö *
( SetRect(spinRect,100,100,300,200); ° d ONLN d,ô <§¬ *
N WITH spinRect DO SetPt(delta,(right - left) DIV 2,(bottom - top) DIV 2); ° d ONLN d{≠ <∏ õ * PenSize(2,2); ° d ONLN dè∑ <¬ • *
PenPat(ltGray); ° d ONLN d•¡ <ÃT *
8 FrameRect(spinRect); { show the unrotated square } ° d ONLN dfiÀ <÷ å *
PenNormal; ° d ONLN dÔfl <Í ** PSRotatedRect(spinRect,delta,angle); ° d ONLN dÛ <˛« *O { QuickDraw equivalent of the rotated object, hidden from PostScript driver } ° d ONLN dj˝ <1 *
1 { because of PostScriptBegin and PostScriptEnd } ° d ONLN dú < *( PicComment(PostScriptBegin,0,NIL); ° d ONLN d≈ <& *
* QDRotatedRect(spinRect,delta,angle); ° d ONLN d% <0 ˙ *
PostScriptEnd ° d ONLN dY √± œ⁄ )[. Some ° d ONLN d` œ € œ ( ˜ 6$applications do not want to restore ° d ONLN dÑ œ œ €⁄ )∑6the previous state of the PostScript interpreter after ° d ONLN dª ‹ Ë ô ( 6including their PostScript ° d ONLN d÷ ‹ ô Ë5 )Å code; for these situations, the ° d ONLN dˆ €5 Áê )ú
PSBeginNoSave ° d ONLN d ‹ê Ë⁄ )[
comment is a ° d ONLN d È ı f ( 6replacement for ° d ONLN d! Ë f Ù œ )NPostScriptBegin ° d ONLN d0 È œ ıØ )i1 that does not preserve the state. Clearly, this ° d ONLN da ÈØ ı⁄ )‡comment ° d ONLN di ı » ( 6$should be used with extreme caution. ° d ONLN dé * *:Some state information may be stored in global variables, ° d ONLN d»*_ (6H so nesting ° d ONLN d”
_» )5PostScriptBegin ° d ONLN d‚»⁄ )i (or ° d ONLN dÁ & z (C 6PSBeginNoSave) ° d ONLN dı z' ë )b and ° d ONLN d˙ ë& Ï )
PostScriptEnd ° d ONLN d Ï'h )[ comments is not allowed. ° d ONLN d!4 @ 1 (\ 6The ° d ONLN d%3 1? ° )PostScriptHandle ° d ONLN d54 °@ä )p+ comment gives developers direct access to ° d ONLN d`4ä@⁄ )ÈPostScript from ° d ONLN dp@ L í (h 6applications. Instead of ° d ONLN dâ@ íL⁄ )z>having the LaserWriter driver convert QuickDraw calls into the ° d ONLN d»L X4 (t 6<corresponding PostScript code, the application can generate ° d ONLN dL4X⁄ (tR#its own PostScript, and transmit it ° d ONLN d(Y e Ò (Å 62to the printer or include it in a picture through ° d ONLN dZY Òe] )Ÿthe data handle of the ° d ONLN dqX]d£ )l
PicComment ° d ONLN d{Y£e⁄ )F procedure. ° d ONLN dáe qy (ç 6BThe handle contains pure ASCII text; the valid length of the data ° d ONLN d…eyq⁄ (çóis specified in the ° d ONLN d›q } ^ (ö 6
PicComment ° d ONLN dÁr ^~ ÷ )F’s size parameter. Don’t ° d ONLN d r ÷~⁄ )x7forget to terminate the PostScript text at least with a ° d ONLN d8~ ä∞ (¶ 6Wspace character, or better with a carriage return (ASCII $0D), so that it is separated ° d ONLN dè~∞ä⁄ (¶Œfrom the ° d ONLN dòä ñg (≤ 6Jfollowing PostScript instructions (either yours, or the printer driver’s). ° d ONLN d„£ Ø | *You must still use ° d ONLN dˆ¢ |Æ Â )dPostScriptBegin ° d ONLN d£ ÂØ )i (or ° d ONLN d
¢Æ\ )
PSBeginNoSave ° d ONLN d£\Ø )[) and ° d ONLN d ¢Æ⁄ )#
PostScriptEnd ° d ONLN d+∞ º < (ÿ 6around ° d ONLN d2Ø <ª ¨ )$PostScriptHandle ° d ONLN dB∞ ¨º; )p comments or the LaserWriter ° d ONLN d_∞;º⁄ )è!driver will not properly save and ° d ONLN dź » È (‰ 6+restore the PostScript drawing environment. ° d ONLN dÆ‘ ‡ ® * As with all picture comments, ° d ONLN dÑ ®‡⁄ )ê=the handle you pass belongs to you and you must dispose of it ° d ONLN d
‡ Ï ¢ ( 6 when you’re finished with it.
° d ONLN d (¯ Ã *$PROCEDURE PostScriptLine(s: Str255); ° d ONLN d M
{ *
G{ A utility procedure to transmit a string of PostScript code through } ° d ONLN d ï { *
G{ the PostScriptHandle picture comment to the PostScript printer. } ° d ONLN d › !{ *
G{ It should be called only between PostScriptBegin and PostScriptEnd } ° d ONLN d
% + Å *
{ picture comments. } ° d ONLN d
;4 ? 6 * VAR ° d ONLN d
B> I h *
h: Handle; ° d ONLN d
SR ] @ * BEGIN ° d ONLN d
\\ g ö *
h := NewHandle(256); ° d ONLN d
wf q *
3 IF h = NIL THEN DebugStr('NewHandle failed'); ° d ONLN d
´p { — *
% BlockMove(@s[1],h^, Length(s)); ° d ONLN d
—z Ö
*
1 PicComment(PostScriptHandle, Length(s), h); ° d ONLN d Ñ è h *
h^^ := 13; ¡ 4¡˘
*+22 )
of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d < (ã ( D ZC PicComment(PostScriptHandle, 1, h); { add a carriage return } ° d ONLN d D ' < 2 Ø *
DisposeHandle(h); ° d ONLN d \ 1 < < _ *
END; ° d ONLN d d O < Z Õ * PROCEDURE PostScriptComments; ° d ONLN d Ç c < n d * BEGIN ° d ONLN d ã m < x *
$ { First, the simple example: } ° d ONLN d ∞ w < Ç *
( PicComment(PostScriptBegin,0,NIL); ° d ONLN d Ÿ Å < åê *
D PostScriptLine('100 100 moveto 0 100 rlineto 100 0 rlineto '); ° d ONLN d ã < ñJ *
6 PostScriptLine('0 -100 rlineto -100 0 rlineto'); ° d ONLN dU ï < † ◊ *
& PicComment(PostScriptEnd,0,NIL); ° d ONLN doI <Tü *G { Let's test to see if the definition from above is still avail-} ° d ONLN d∑S <^ü *
G { able. This assumes that no font downloading has occurred. } ° d ONLN dˇg <r *( PicComment(PostScriptBegin,0,NIL); ° d ONLN d(q <|^ *
: PostScriptLine('//userdict /myFrameRect get exec '); ° d ONLN dc{ <Ü ˙ *
& PicComment(PostScriptEnd,0,NIL); ° d ONLN däÖ <ê _ *
END;
° d ONLN díû <™ b *Caveat ° d ONLN dô∂ <¬ *,If you choose to use PostScript directly in ° d ONLN d≈∂ ¬˛ )·*your pictures, be very careful not to make ° d ONLN d√ <œ z (Î Z assumptions ° d ONLN d¸√ zœ ¡ )>about Apple’s ° d ONLN d
¬ ¡Œ › )G"md" ° d ONLN d√ ›œ˛ ) = dictionary (essentially the contents of the former LaserPrep ° d ONLN dLœ <€ (˜ Z/file). Otherwise, your pictures will not print ° d ONLN d{œ€˛ )Ÿ0correctly with future versions of the PostScript ° d ONLN d¨€ <Á` ( Z=LaserWriter driver. Also, be aware of compatibility problems ° d ONLN dÈ€`Á˛ (~ within the PostScript world, and ° d ONLN d
Á <Û/ ( Z/watch out for printers with PostScript Level 1 ° d ONLN d9Á/Û˛ )Û(and PostScript Level 2 interpreters, and ° d ONLN dbÛ <ˇ6 ( Z5“PostScript-compatible” printers (PostScript clones).
° d ONLN dò <& *' FormsPrinting Picture Comments
° d ONLN d∑2 <> { * Comments: ° d ONLN d¡2 Ñ>( )H FormsPrinting, EndFormsPrinting ° d ONLN d·K <W R (s ZThe ° d ONLN dÂJ RV ≠ )
FormsPrinting ° d ONLN dÚK ≠Wz )[* comment tells the PostScript LaserWriter ° d ONLN d KzW˛ )Õ driver not to clear its page ° d ONLN d9X <d v (Ä Z
buffer after ° d ONLN dFX vd … ):printing a page. ° d ONLN dWW …c9 )SEndFormsPrinting ° d ONLN dgX9d˛ )p& turns this mode off. When the page is ° d ONLN déd <p∏ (å ZLcompleted, the application must erase the areas that need to be updated and ° d ONLN d⁄d∏p˛ (å÷ draw the new ° d ONLN dÁp <|` (ò Z:information. The graphics that make up the form are drawn ° d ONLN d !p`|˛ (ò~ only once per page, which may ° d ONLN d ?| <à ™ (§ Zimprove performance. ° d ONLN d T| ™à˛ )nECurrently, you need to write special printing code for the PostScript ° d ONLN d öà <î1 (∞ Z3LaserWriter driver if you want to use this comment. ¡ X¡
*&&QD 10 - Picture Comments—The Real Deal (÷˙23 )
of 26 (Ï ZM.QD.PictComments ˇ™ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d 5 DÇ *33(More or Less) Obsolete PostScript Picture Comments
° d ONLN d 4 Q ] W * Comments: ,
Courier ° d ONLN d > P ` \ ¥ )H SetGrayLevel ° d ONLN d J Q ¥ ] ∏ )T, ° d ONLN d M ] ` i – ( Ü ~TextIsPostScript ° d ONLN d ] ^ – j ◊ )p, ° d ONLN d _ ] ◊ i )
DrawString ° d ONLN d= È: ıC )F, ° d ONLN d? ËC Ù{ ) DrawText ° d ONLN dG È{ ı» )8, and anything ° d ONLN dV È» ı⁄ )Melse ° d ONLN d[ ˆ à ( 6that eventually calls the ° d ONLN du ı à π )pStdText ° d ONLN d| ˆ πC )1 bottleneck), and interprets it ° d ONLN dú ˆC⁄ )ä as a PostScript program. There ° d ONLN dª é (* 6is no good reason to use ° d ONLN d‘ é⁄ )vFthis picture comment, but there is one important reason not to use it: ° d ONLN d º (7 6!Printer drivers that do not deal ° d ONLN d< º Ì )§ with the ° d ONLN dE Ì] )1TextIsPostScript ° d ONLN dU]⁄ )p comment will print the ° d ONLN dm '™ (C 6YPostScript text instead of interpreting it! If you need to transmit pure PostScript code ° d ONLN dΔ™'⁄ (C» directly to ° d ONLN d“( 4 b (P 6a printer that ° d ONLN d·( b4 „ )Junderstands it, use the ° d ONLN d˘' „3S )ÅPostScriptHandle ° d ONLN d (S4⁄ )p comment, and include a ° d ONLN d!4 @ (\ 67QuickDraw representation for all other printer drivers. ° d ONLN dYM Y / *The ° d ONLN d]L /X u )
ResourcePS ° d ONLN dgM uY> )F' picture comment loads PostScript code ° d ONLN déM>Y⁄ )… from a specified resource. The ° d ONLN d≠Z f (Ç 66resource file is expected to be open at the time that ° d ONLN d„Zf )Ôthe ° d ONLN dÁYe_ )
ResourcePS ° d ONLN dÒZ_f⁄ )F comment is used. Under ° d ONLN d f r ˙ (é 6-background printing, there are no guarantees ° d ONLN d6f ˙r⁄ )‚-the file will still be open when the Printing ° d ONLN ddr ~a (ö 6FManager needs it. For this reason alone, you should forget about this ° d ONLN d™ra~⁄ (öcomment. If you want to ° d ONLN d¬~ ä 2 (¶ 6keep ° d ONLN d«~ 2ä⁄ )YPostScript instructions in a resource, it is easy to write a small routine that loads the ° d ONLN d!ã ó Í (≥ 6-resources and sends their contents using the ° d ONLN dNä ÍñZ )“PostScriptHandle ° d ONLN d^ãZó] )p ° d ONLN d_ã]ó⁄ )comment described earlier ° d ONLN dyó £ S (ø 6
in this Note. ° d ONLN dáØ ª z *PostScriptFile ° d ONLN dï∞ zº º )b has the same ° d ONLN d£∞ ºº ˙ )B problems as ° d ONLN dØØ ˙ª@ )>
ResourcePS ° d ONLN dπ∞@º⁄ )F described above. Basically, the ° d ONLN d⁄º »ô (‰ 6SPrinting Manager cannot guarantee that the file will be available when it’s needed.
° d ONLN d.‡ Ôc *'/Appendix: Pascal Interface for Picture Comments
° d ONLN d^¸ . *(File ° d ONLN dc˚ . ó ) PicComments.p)
° d ONLN ds 1 (; 6CONST ° d ONLN dy ) w *
TextBegin = 150; ° d ONLN dç( 3 m *
TextEnd = 151; ° d ONLN dü2 = Å *
StringBegin = 152; ° d ONLN dµ< G w *
StringEnd = 153; ° d ONLN d…F Q | *
TextCenter = 154; ° d ONLN dfiP [ ã *
LineLayoutOff = 155; ° d ONLN dˆZ e Ü *
LineLayoutOn = 156; ° d ONLN d
d o ö *
ClientLineLayout = 157; ° d ONLN d (n y w *
PolyBegin = 160; ° d ONLN d <x É m *
PolyEnd = 161; ° d ONLN d NÇ ç | *
PolyIgnore = 163; ° d ONLN d cå ó | *
PolySmooth = 164; ¡ 4¡˘
*#24 )
of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇ î ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d < ( õ ( D Z PolyClose = 165; ° d ONLN d ' < 2 † *
J intervals: ARRAY [0..5] { Array of dash intervals } ° d ONLN d Ω »ä *
J OF SignedByte; { intervals[0] = number } ° d ONLN da « “ä *
J END; { of interval specs. } ° d ONLN d¨ € Ê ¬ *" TLineWidthHdl = ^TLineWidthPtr; ° d ONLN dœ  ≥ *
TLineWidthPtr = ^TLineWidth; ° d ONLN dÔ Ô ˙N *
> TLineWidth = Point; { v = numerator, h = denominator. } ° d ONLN d. ≤ *R TClientLLHdl = ^TClientLLPtr; { used in the ClientLineLayout picture comment } ° d ONLN dÅ
∏ *
TClientLLPtr = ^TClientLLRec; ° d ONLN d¢ " $ *
° d ONLN d§ $" í ) TClientLLRec = RECORD ° d ONLN dª! ,ä (H 6J chCount : Integer; { Apply for so many characters. } ° d ONLN d+ 6≤ *
R major : Fixed; { percentage of line layout error to be } ° d ONLN dY5 @≤ *
R { distributed among space characters. } ° d ONLN d¨? J≤ *
R spcChar : Integer; { code of character that is to absorb } ° d ONLN dˇI T≤ *
R { the "major" line layout error } ° d ONLN dRS ^≤ *
R minor : Fixed; { percentage of intercharacter distrib. } ° d ONLN d•] h≤ *
R ulLength: Fixed; { underline length. } ° d ONLN d¯g r Ü *
END;
° d ONLN dï ° Ç */Further Reference: ¿ 4¿˘ ° d ONLN d"¢ *Æ . +
• ° d ONLN d$¢ <Æ ˆ )$PostScript Language Reference Manual ° d ONLN dH¢ ˆÆ] )∫, Adobe Systems Inc. ° d ONLN d]Æ *∫ . (÷ H• ° d ONLN d_Æ <∫ ç )Inside Macintosh ° d ONLN doÆ ç∫ ˇ )Q, Volumes II, V, and VI ° d ONLN dá∫ *Δ . (‚ H• ° d ONLN dâ∫ <Δ Ã ) LaserWriter Reference Manual ° d ONLN d•∫ ÃΔ" )ê, Addison-Wesley ° d ONLN d∂Δ *“ . (Ó H• ° d ONLN d∏Δ <“B )/Macintosh Technical Note M.IM.AppPictComments — ° d ONLN dΓ `fiP +$ 2Every Picture [Comment] Tells Its Story, Don’t It? ° d ONLN d fi *Í . ( H• ° d ONLN d fi <Í5 )/Macintosh Technical Note M.IM.PictAndPrinting — ° d ONLN dRÍ `ˆ +$ !Pictures and the Printing Manager ° d ONLN dtˆ * . ( H• ° d ONLN dvˆ <_ ):develop Issue 3, “Meet PrGeneral” by Pete “Luke” Alexander ° d ONLN d± & (B 63Adobe is a trademark of Adobe Systems Incorporated. ° d ONLN dÂ& 2\ * CPostScript is a registered trademark of Adobe Systems Incorporated. ¡ 4¡˘
*à26 )
of 26 (÷F&QD 10 - Picture Comments—The Real Deal +YM.QD.PictComments ˇƒ ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. eRSeRS +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d o < Ç[ ( ú Z!QD 11 - Pictures and Clip Regions
° d ONLN d " Å < ê á * QuickDraw
° d ONLN d - ú < ® t * Revised by: ° d ONLN d : ú¬ ®˛ ( ƒ‡ March 1988 ° d ONLN d F ® < ¥ q ( – Z Written by: ° d ONLN d R ® Ñ ¥ ’ )HJennifer Jernigan ° d ONLN d d ®æ ¥˛ ( –‹ January 1986 ° d ONLN d q ¿ < Ãô ( Ë ZJThis note describes a problem that affects creation of QuickDraw pictures. ˜ X ˜ ° d ONLN d º Ê < Ú e *&When a ,
Courier ° d ONLN d √  e Ò ù ))GrafPort ° d ONLN d À Ê ù Ú% )8 is created, the fields in the ° d ONLN d Í Â% Ò] )àGrafPort ° d ONLN d Ú Ê] Úa )8 ° d ONLN d Û Êa Ú˛ ) are given default values; one of ° d ONLN d Ú < ˛ Á ( Z'these is the clip region, which is set ° d ONLN d; Ú Á ˛˛ )´7to the rectangle (–32767, –32767, 32767, 32767). If you ° d ONLN ds ˇ < ≥ (' Z create a picture, then call ° d ONLN dè ˛ ≥
)w DrawPicture ° d ONLN dö ˇ )M ° d ONLN dõ ˇ ˛ )6with a destination rectangle that is not the same size ° d ONLN d“ < Z (4 Zas the ° d ONLN dŸ Z í ) picFrame ° d ONLN d· í⁄ )8F without ever changing the default clip region, nothing will be drawn. ° d ONLN d($ <0â (L ZFWhen the picture frame is compared with the destination rectangle and ° d ONLN dn$â0˛ (Lßthe picture is scaled, the ° d ONLN dâ0 << P (X Zclip ° d ONLN dé0 P<˛ )Yregion is scaled too. In the process of scaling, the clip region you end up overflows and ° d ONLN dË< <HÓ (d Z:becomes empty, and your picture doesn’t get drawn. If you ° d ONLN d"<ÓH˛ (d call ° d ONLN d'H <T ˘ (q ZClipRect(thePort^.portRect) ° d ONLN dBI ˘Us )Ω before you record the ° d ONLN dYIsU˛ )z picture, the picture will be ° d ONLN dvU <a È (} Z!drawn correctly. The clipping on ° d ONLN dóU Èa˛ )≠5the destination port when playing back the picture is ° d ONLN dÕa <m\ (â ZCirrelevant: once a picture is incorrectly recorded, it is too late. ° d ONLN dë <ù ¶ *0Further Reference: º Xº ° d ONLN d$û N™ R +
• ° d ONLN d&û `™ ñ ) QuickDraw ¡ X¡
(÷ Z!QD 11 - Pictures and Clip Regions (÷1 ) of 1 (Ï ZM.QD.PicturesAndClipRegions ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. WIQkWIQk +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d o < Ç- ( ú Z QD 12 - Plotting Small Icons
° d ONLN d Å < ê á * QuickDraw
° d ONLN d ( ú < ® t * Revised by: ° d ONLN d 4 ú Ñ ® ‹ )HJames Beninghaus ° d ONLN d E úæ ®˛ ( ƒ‹ October 1989 ° d ONLN d R ® < ¥ q ( – Z Written by: ° d ONLN d ^ ® Ñ ¥3 )H James Beninghaus & Dennis Hescox ° d ONLN d ®¡ ¥˛ ( –fl August 1989 ° d ONLN d ã ¡ < Õ Ó ( È Z"This Technical Note discusses the ,
Courier ° d ONLN d ≠ ¿ Ó Ã )≤'SICN' ° d ONLN d ≥ ¡ Õ˛ )*) resource format and how to plot one in a ° d ONLN d › Õ < Ÿ t ( ˆ ZGrafPort ° d ONLN d  Œ t ⁄ x )8. ° d ONLN d Á ⁄ < Ê › ( ZChanges since August 1989: ° d ONLN d ⁄ › Ê˚ )°> Corrected errors in the Pascal code and spruced up the rest. X
resource ° d ONLN dF@lL˛ ). to the Notification Manager or ° d ONLN deL <X ä (t ZMenu Manager, ° d ONLN dsL äX˛ )NKand they will draw it for you automatically—you should continue to let them ° d ONLN døX <d: (Ä Z2do so. However, if you want to draw a small icon ° d ONLN dÒX:d˛ )˛'in your application’s window, then this ° d ONLN dd <p Å (å ZNote can help. ° d ONLN d(} <â y * What does a ° d ONLN d4| yà £ )='SICN' ° d ONLN d:} £â( )* look like? Following is a ° d ONLN dV|(àR )Ö'SICN' ° d ONLN d\}RⲠ)*# representation of a dogcow to help ° d ONLN dÄâ <ï † (± Zanswer this question: † Ç
¿ Èç ò ë ® ËP ë ® ËL¿ Èç Î Î ¯ ˜ˇ¿ ¯ ˜ @ ¯ ¸ ¿Ä @ ¯ ¸ ¿Ä @ ¯ !¸ ¿Ä @ ¯ ¸ ¿Ä @ ¯ Ř @ ¯ ¸ x < @ ˘ ¸ x < @ ¯ ¸ x < @ ˘ ¸ x < @ ¯ ˜ @ ˘ ¸ x < @ ¯ ¸ x < @ ˘ ĸ x < @ ¯ ¸ x < @ ˙ ˜ @ ¯ ¿˛ ¿‡@ ˙ ¿˛ ¿‡@ ¯ ¿˛ ¿‡@ ˙ ¿˛ ¿‡@ ¯ ˜ @ ˙ Ä {¿˛ ¿ @ ¯ {¿˛ ¿ @ ˚ {¿˛ ¿ @ ¯ {¿˛ ¿ @ ˚ ˜ @ ¯ x ˛ x˛ @ ˚ x ˛ x˛ @ ¯ x ˛ x˛ @ ˚ Ä x ˛ x˛ @ ¯ ˜ @ ¸ ˛ x ˜ΩÔx Ω‡@ ¯ x ˜ΩÔx Ω‡@ ¸ ˛ x ˜ΩÔx Ω‡@ ¯ x ˜ΩÔx Ω‡@
IR ° d ONLN dñ ¿ Ë +Ñ|SICN' ° d ONLN dûPy )êFatBits ° d ONLN d¶ <)j (E Z@There is reason to believe that this representation is actually ° d ONLN dÊ j)˛ (Eàa baby dogcow. Due to the ° d ONLN d) <5î (Q ZEprotective nature of parent dogcows, young dogcows are rarely seen. ° d ONLN dF)î5˛ (Q≤This one was spotted ° d ONLN d[5 <A „ (] Z#during a DTS meeting after it drew ° d ONLN d~5 „A˛ )ß<attention to itself by crying “moo! woof!”. (Note that this ° d ONLN dªA <Mı (i ZXdogcow said “moo! woof!” because it was immature; adult dogcows naturally say, “Moof!”.) ¡ X¡
*m QD 12 - Plotting Small Icons (÷1 ) of 5 (Ï ZM.QD.PlottingSmallIcons ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø
L ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 8 Ü *''SICN' Resource
° d ONLN d E Q % *A ,
Courier ° d ONLN d D % P O )
'SICN' ° d ONLN d E O Q¨ )*D resource contains any number of small icon bit images. Each small ° d ONLN d \ E¨ Q⁄ ( m icon in a ° d ONLN d f Q ] B ( z 6'SICN' ° d ONLN d l R B ^¥ )*J list describes a 16 by 16 pixel image and requires 32 bytes of storage. ° d ONLN d ∂ R¥ ^⁄ ( z“Like an ° d ONLN d æ ^ j K ( á 6'ICN#' ° d ONLN d ≈ _ K k ‰ )3 resource, there is no count of ° d ONLN d ‰ _ ‰ ké )ô the number of icons stored in a ° d ONLN d ^é j∏ )™'SICN' ° d ONLN d
_∏ k⁄ )*. The ° d ONLN d l x I ( î 6
following ° d ONLN d k I w s )1'SICN' ° d ONLN d! l s xÇ )*7 resource, in MPW Rez format, contains two small icons:
° d ONLN dZ Ñ < è Ê ( ´ Z"resource 'SICN' (1984, "clarus") { ° d ONLN d é ` ô e +$
{ ° d ONLN dÅ é Ñ ô ˜ )$/* array: 2 elements */ ° d ONLN dú ¢ Ñ ≠~ *2$"00 48 00 B4 00 84 40 52 C0 41 A0 81 9F 8E 8F 18" ° d ONLN d“ ¨ Ñ ∑É *
3$"40 18 40 18 47 88 48 48 48 48 44 44 3C 3C 00 00", ° d ONLN d ¿ Ñ À~ *2$"00 48 00 FC 00 FC 40 7E C0 7F E0 FF FF FE FF F8" ° d ONLN d? Ñ ’~ *
2$"7F F8 7F F8 7F F8 78 78 78 78 7C 7C 3C 3C 00 00" ° d ONLN dt ‘ ` fl e ( ˚ ~} ° d ONLN dw fi < È F ( Z};
° d ONLN dz “ (+ 6The Right Tools for the Job
° d ONLN dñ 'x *HThe Macintosh Toolbox interfaces do not describe all the necessary data ° d ONLN dfix'⁄ (Cñstructures needed to ° d ONLN dÛ( 4 N (P 6
work with ° d ONLN d˝' N3 x )6'SICN' ° d ONLN d( x4 ± )* resources. ° d ONLN d( ±4∞ )91 As shown in the following example, defining the ° d ONLN d@'∞3⁄ )ˇ'SICN' ° d ONLN dG4 @ < (\ 6type as ° d ONLN dO4 <@⁄ )$Wan array of 16 short integers and the handles and pointers to this array type make life ° d ONLN dß@ L T (h 6 much easier. ° d ONLN d¥X d < *Pascal
° d ONLN dªp { , *TYPE ° d ONLN d¿z Ö *
/ SICN = ARRAY[0 .. 15] of INTEGER; ° d ONLN dÑ è Ô *
+ SICNList = ARRAY[0 .. 0] of SICN; ° d ONLN d é ô ≥ *
SICNPtr = ^SICNList; ° d ONLN d<ò £ Æ *
SICNHand = ^SICNPtr;
° d ONLN d[Æ ∫ ! *C
° d ONLN d]Δ — ∏ * typedef short SICN[16]; ° d ONLN d~– € Ω *
!typedef SICN *SICNList; ° d ONLN d†⁄ Â Ω *
!typedef SICNList *SICNHand;
° d ONLN d¬¸ ï *&The Missing Count
° d ONLN d‘ $ - *The ° d ONLN dÿ -# W )'SICN' ° d ONLN dfi W$ê )*C resource does not provide a count to indicate the number of small ° d ONLN d!ê$⁄ (@Æicons contained ° d ONLN d1$ 0≤ (L 6Xwithin; however, you can easily determine this number by dividing the total size of the ° d ONLN dâ$≤0⁄ (L–resource ° d ONLN dí0 < µ (X 6#by the size of a single small icon. ¡ 4¡˘
*~2 ) of 5 (ր QD 12 - Plotting Small Icons +
M.QD.PlottingSmallIcons ˇ
‘ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1989 / X /
° d ONLN d ) < 5 ` ( Q ZPascal ,
Courier
° d ONLN d A < L U *CONST ° d ONLN d
K < V æ *
mySICN = 1984; ° d ONLN d ( U < ` K *
VAR ° d ONLN d , _ < j “ *
theSICN : SICNHand; ° d ONLN d K i < t Õ *
theSize : LONGINT; ° d ONLN d i s < ~ Õ *
theCount : LONGINT; ° d ONLN d á } < à Õ *
theIndex : LONGINT; ° d ONLN d • ë < ú1 *1theSICN := SICNHand(GetResource('SICN', mySICN)); ° d ONLN d ◊ õ < ¶ “ *
IF (theSICN <> NIL) THEN BEGIN ° d ONLN d ˆ • < ∞1 *
, theCount := theSize DIV sizeof(SICN); ° d ONLN dU π < ƒ P *
END;
° d ONLN dZ œ < € E *C
° d ONLN d\ Á < Ú √ *#define mySICN 1984 ° d ONLN dx ˚ < õ *SICNHand theSICN; ° d ONLN då < õ *
long theSize; ° d ONLN d† < † *
long theCount; ° d ONLN dµ <$ † *
long theIndex; ° d ONLN d - <81 *1theSICN = (SICNHand) GetResource('SICN', mySICN); ° d ONLN d¸7 <B Ç *
if (theSICN) { ° d ONLN d A <L, *
0 theSize = GetHandleSize((Handle)theSICN); ° d ONLN d<K <V *
) theCount = theSize / sizeof(SICN); ° d ONLN dfU <` A *
}
° d ONLN dhw <Ü ≠ *&The Plot 'SICN's
° d ONLN dyì <ü ≠ *The example procedure ° d ONLN dèí ≠û  )qPlotSICN ° d ONLN dóì Âü8 )8 draws one small ° d ONLN d®ì8üg )S
icon of a ° d ONLN d≤ígûë )/'SICN' ° d ONLN d∏ìëü˛ )* resource. It takes the ° d ONLN d—† <¨ | (» Z handle from ° d ONLN d›ü |´ ≠ )@theSICN ° d ONLN d‰† ≠¨^ )1# and the position in the list from ° d ONLN dü^´ñ )±theIndex ° d ONLN d†ñ¨˛ )8 within the rectangle ° d ONLN d%¨ <∏ m (’ ZtheRect ° d ONLN d,≠ mπ ≤ )1 of the current ° d ONLN d<¨ ≤∏ Í )EGrafPort ° d ONLN dD≠ Íπ Ó )8. ° d ONLN dFΔ <“ p (Ó Z
Following ° d ONLN dPΔ p“ ◊ )4is an example call to ° d ONLN df≈ ◊— )gPlotSICN ° d ONLN dnΔ“˛ )83 which plots all the small icons in a resource into ° d ONLN d¢“ <fi ï (˙ Zthe same rectangle: ° d ONLN d∂Í <ˆ ` *Pascal
° d ONLN dΩ <
◊ * SetRect(theRect, 0, 0, 16, 16); ° d ONLN d› < Ê *
"FOR theIndex := 0 TO theCount-1 DO ° d ONLN d <! *
, PlotSICN(theRect, theSICN, theIndex);
° d ONLN d-, <8 E *C
° d ONLN d/D <O ‹ * SetRect(&theRect, 0, 0, 16, 16); ° d ONLN dPN <Y@ *
° d ONLN d≥o <{ ≥ *Because PlotSICN uses ° d ONLN d…n ≥z Ú )w _CopyBits ° d ONLN d“o Ú{ )? and ° d ONLN d◊n zJ ) _CopyBits ° d ONLN d‡oJ{≈ )? can move memory, you ° d ONLN dˆo≈{˛ ){ should lock ° d ONLN d| <à (§ ZCthe handle to the 'SICN' once the resource is loaded. Notice that ° d ONLN dE|àí (§ùthe ° d ONLN dI{íá )PlotSICN ° d ONLN dQ| à˛ )8
procedure ¡ X¡
(÷ Z QD 12 - Plotting Small Icons (÷3 ) of 5 (Ï ZM.QD.PlottingSmallIcons ˇ8 ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d * X *
dereferences ° d ONLN d
X * l )@the ,
Courier ° d ONLN d l ) ñ )'SICN' ° d ONLN d ñ *⁄ )*@ handle, adds an offset, and copies the resulting value. If the ° d ONLN d X * 6 B ( S 6'SICN' ° d ONLN d ^ + B 7% )*1 list moves in memory at this time, the bitmap’s ° d ONLN d è *% 6] )„baseAddr ° d ONLN d ó +] 7ë )8 is useless. ° d ONLN d § D P j ( l 6To play it safe, ° d ONLN d µ C j O ¢ )RPlotSICN ° d ONLN d Ω D ¢ P Δ )8 saves ° d ONLN d ƒ D Δ P⁄ )$6a copy of the master pointer flags associated with the ° d ONLN d ˚ Q ] ( y 62relocatable block, locks the block with a call to ° d ONLN d- P \* )Ë_HLock ° d ONLN d3 Q* ]2 )*, ° d ONLN d5 Q2 ]⁄ )$and restores the flags after calling ° d ONLN dZ ] i W ( Ü 6 _CopyBits ° d ONLN dc ^ W j £ )?. You should ° d ONLN dq ^ £ j ¬ )Lnever ° d ONLN dv ^ ¬ j « ) ° d ONLN dw ^ « j⁄ )7examine, set, or clear these flags directly; you should ° d ONLN dØ j v < ( í 6always ° d ONLN d∂ j < v⁄ )$Ouse the routines which are provided by the Memory Manager and Resource Manager. ° d ONLN d v Çl ( û 6NNote that it is not necessary to check the value of the flag after getting it. ° d ONLN dV é ö < *Pascal
state : SignedByte; ° d ONLN dà ∫ à ≈≤ )¥.{ we want a chance to restore original state } ° d ONLN d˚ ƒ œ § ( Î 6 srcBits : BitMap; ° d ONLN d ƒ à œè )¥'{ built up around 'SICN' data so we can ° d ONLN d@ Œ Ÿ
( ı 61 _CopyBits } ° d ONLN dr ‚ Ì 1 *BEGIN ° d ONLN dx Ï ˜ Ù *
, { check the index for a valid value } ° d ONLN d• ˆ è *
K IF (GetHandleSize(Handle(theSICN)) DIV sizeof(SICN)) > theIndex THEN ° d ONLN dÒ T *
BEGIN ° d ONLN d˛ q *E { store the resource's current locked/unlocked condition } ° d ONLN dD ) *
/ state := HGetState(Handle(theSICN)); ° d ONLN dt2 =è *K { lock the resource so it won't move during the _CopyBits call } ° d ONLN d¿< G ¬ *
" HLock(Handle(theSICN)); ° d ONLN d„P [ ˘ *- { set up the small icon's bitmap } ° d ONLN dZ e r *
{$PUSH} ° d ONLN d$d o h *
{$R-} ° d ONLN d7d ÃoS )¥{ turn off range checking } ° d ONLN dSn y5 (ï 69 srcBits.baseAddr := Ptr(@theSICN^^[theIndex]); ° d ONLN dçx É m *
{$POP} ° d ONLN düÇ ç Ω *
! srcBits.rowBytes := 2; ° d ONLN d¡å ó
*
1 SetRect(srcBits.bounds, 0, 0, 16, 16); ° d ONLN dÛ† ´: *: { draw the small icon in the current grafport } ° d ONLN d.™ µ≤ *
R CopyBits(srcBits,thePort^.portBits,srcBits.bounds,theRect,srcCopy,NIL); ° d ONLN dÅæ …S *? { restore the resource's locked/unlocked condition } ° d ONLN d¡» ” ˘ *
- HSetState(Handle(theSICN), state); ° d ONLN dÔ“ › O *
auto char state; ° d ONLN d` Ã+£ )¥+/* saves original flags of 'SICN' handle */ ° d ONLN då* 5 Ω (Q 6! auto BitMap srcBits; ° d ONLN dÆ* Ã5î )¥(/* built up around 'SICN' data so we can ° d ONLN d◊4 ? ([ 62 _CopyBits */ ° d ONLN d
H S ˛ *. /* check the index for a valid value */ ° d ONLN d9R ]Ä *
H if ((GetHandleSize(Handle(theSICN)) / sizeof(SICN)) > theIndex) { ° d ONLN dÇf q{ *G /* store the resource's current locked/unlocked condition */ ° d ONLN d p { ˛ *
. state = HGetState((Handle)theSICN); ¡ 4¡˘
*?4 ) of 5 (ր QD 12 - Plotting Small Icons +
M.QD.PlottingSmallIcons ˇ¨ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1989 / X / ,
Courier
° d ONLN d ' < 2Ω ( N ZM /* lock the resource so it won't move during the _CopyBits call */ ° d ONLN d N 1 < < Ê *
" HLock((Handle)theSICN); ° d ONLN d q E < P' */ /* set up the small icon's bitmap */ ° d ONLN d ° O < ZY *
9 srcBits.baseAddr = (Ptr) (*theSICN)[theIndex]; ° d ONLN d € Y < d ‹ *
. HSetState((Handle) theSICN, state); ° d ONLN d8 ≥ < æ d *
} ° d ONLN dA Ω < » A *
}
° d ONLN dC fl < Ó û *&
That Was Easy
° d ONLN dQ ˙ <8 *4Now that you’ve seen it done, it looks pretty easy. ° d ONLN dÖ ˙8˛ )¸& With minor modifications, some of the ° d ONLN d¨ <ß (. ZMtechniques in this Note could also be used to plot a bitmap of any dimension. ° d ONLN d˙6 <B ¶ *0Further Reference: a Xa ° d ONLN d
C NO R +
• ° d ONLN dC `O ± )Inside Macintosh ° d ONLN d C ±O! )Q, Volume I, QuickDraw ° d ONLN d5O N[ R (w l• ° d ONLN d7O `[ ± )Inside Macintosh ° d ONLN dGO ±[; )Q , Volume I, Toolbox Utilities ° d ONLN de[ Ng R (É l• ° d ONLN dg[ `g ± )Inside Macintosh ° d ONLN dw[ ±g\ )Q , Volume IV, The Memory Manager ° d ONLN dóg Ns R (è l• ° d ONLN dôg `s* )%Technical Note M.IM.OffscreenBitMap — ° d ONLN d¡s Ñ1 +$ " Drawing Into an Off-Screen BitMap ° d ONLN d‰ Nã R (ß l• ° d ONLN dÊ `ã )"Technical Note M.IM.DrawingIcons — ° d ONLN d ã Ñó Õ +$ Drawing Icons ¡ X¡
(÷ Z QD 12 - Plotting Small Icons (÷5 ) of 5 (Ï ZM.QD.PlottingSmallIcons ˇF ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < Åı ( õ Z2QD 13 - Principia Off-Screen Graphics Environments
° d ONLN d 3 Ä < è á * QuickDraw
° d ONLN d > õ < ß v * Updated by: ° d ONLN d J õ Ñ ß À )HForrest Tanaka ° d ONLN d Y õ≈ ߲ ( √„
March 1992 ° d ONLN d d ß < ≥ q ( œ Z Written by: ° d ONLN d p ß Ñ ≥ À )HForrest Tanaka ° d ONLN d ßæ ≥˛ ( œ‹ October 1991 ° d ONLN d å ≥ < ø u ( € Z Inspired by: ° d ONLN d ô ≥ Ñ ø\ )H-Jim Friedlander, Rick Blair, and Rich Collyer ° d ONLN d « À < ◊K ( Û Z5Using Color QuickDraw to draw off screen is a common ° d ONLN d ¸ ÀK ◊˛ ( Ûi%requirement of applications and other ° d ONLN d" ◊ < „ Z ( ˇ Zkinds ° d ONLN d( ◊ Z „˛ ) Oof programs that run on the Macintosh. This Note discusses what Color QuickDraw ° d ONLN dx „ < ÔË ( ZPneeds in a graphics environment and how to create one for off-screen drawing. A ° d ONLN d» „Ë Ô˛ ( brief ° d ONLN dŒ Ô < ˚ ( ZUdiscussion of GWorlds, which are off-screen graphics environments that are set up by ° d ONLN d# Ô ˚˛ (the ° d ONLN d' ˚ < Û (# Z$system, is given to help you decide ° d ONLN dK ˚ Û˛ )∑4whether to use them or the do-it-yourself techniques ° d ONLN dÄ <T (/ Z=described in this Note for setting up an off-screen graphics ° d ONLN dΩT˛ (/r#environment. The author’s intent is ° d ONLN d· < H (; Zto ° d ONLN d‰ H ˛ ) Zprovide concepts and routines for creating an off-screen graphics environment, and also to ° d ONLN d? <+| (G ZDexplain why existing routines for off-screen drawing act as they do. ° d ONLN dÑ7 <C Q *Man ° d ONLN dá7 QC W )y ° d ONLN dà7 VC ] ), ° d ONLN dä7 ]C˛ )Qmany thanks go to Guillermo Ortiz, Konstantin Othmer, Bruce Leak, and Jon Zap for ° d ONLN d‹C <O (k Z3all their expertise on this subject, Rich Collyer, ° d ONLN dC O˛ )·.Rick Blair, and Jim Friedlander for paving the ° d ONLN d>O <[ J (w Zwa ° d ONLN d@O J[ P )y ° d ONLN dAO O[ õ ), and especially ° d ONLN dRO õ[˛ )LIto all people who inspired this update by asking great off-screen drawing ° d ONLN dú[ <g m (É Z
questions. ° d ONLN dßs < ‡ *Changes since October 1991 ° d ONLN d¡s ‡i )§: A very embarrassing bug ° d ONLN d‹si˛ )â was found in CreateOffScreen ° d ONLN d˘ <ã ∑ (ß Zand UpdateOffScreen. If ° d ONLN d ∑ã˛ ){Byou try to create a 16- or 32-bit off-screen graphics environment, ° d ONLN dTã <ó (≥ Z1you’ll just get a paramErr. It won’t do that now. ¬ X¬
any of the ° d ONLN d ∑ 5 AJ ( ] 6Cresults. This is off-screen drawing. There are plenty of perfectly ° d ONLN d ˙ 5J A⁄ ( ]h good reasons to do this, such ° d ONLN d A M$ ( i 66as providing storage for a paint-style document or to ° d ONLN dN A$ M⁄ ( iB"smoothly animate an image, but the ° d ONLN dq M Y† ( u 6Sassumption here is that you have a perfectly good reason to do this so you’re more ° d ONLN dƒ M† Y⁄ ( uæ
interested in ° d ONLN d“ Y e K ( Å 6
the “how” ° d ONLN d‹ Y K e^ )38of it instead of the “why” of it. If you need to know wh ° d ONLN d Y^ ed ( Å|y ° d ONLN d Yc e⁄ ), there are several books ° d ONLN d/ e q ( ç 65that cover off-screen drawing and the perfectly good ° d ONLN dd e q⁄ )˙(reasons to do such a thing. A good place ° d ONLN dç q } ± ( ô 6"to start is Scott Knaster’s book, ° d ONLN dØ q ± }) )ôMacintosh Programming ° d ONLN d≈ q) }K )xSecrets ° d ONLN dà qK }⁄ )" , referenced at the end of this ° d ONLN dÏ } â 3 ( • 6Note. ° d ONLN dÚ ï ° Ú */This Note is divided into these major sections: ° d ONLN d" ≠ * π( +7• The introduction is the part that you’re reading now. ° d ONLN dZ π * ≈ † * • “The Building Blocks” ° d ONLN dr π † ≈∂ )v9provides an overview of the data structures that you need ° d ONLN d¨ ≈ 7 — ( Ì U+to tell Color QuickDraw to draw off screen. ° d ONLN dÿ — * › — ( ˘ H"• “Building the Blocks” discusses ° d ONLN d˙ — — ›∂ )ß1the construction and initialization of these data ° d ONLN d, › 7 È i ( U structures. ° d ONLN d8 È * ı . ( H• ° d ONLN d: È 7 ı ÷ )
“Playing With Blocks” shows an ° d ONLN dY È ÷ ı∂ )ü.example of the use of these structures to draw ° d ONLN dà ı 7 j ( U off screen. ° d ONLN dî *
. () H• ° d ONLN dñ 7
v )
>“Put That Checkbook Away!” discusses some variations of these ° d ONLN d‘v
∂ ()î
techniques to ° d ONLN d‚
7 (5 U,handle off-screen drawing for special cases. ° d ONLN d *% . (A H• ° d ONLN d 7% ’ )
“The GWorld Factor” provides a ° d ONLN d0 ’%∂ )û+brief overview of GWorlds, how to use them, ° d ONLN d\% 71≠ (M UNand how they compare and contrast to the manual techniques that are described ° d ONLN d™%≠1∂ (MÀin ° d ONLN d≠1 7= ç (Y Umost of this Note. ° d ONLN d¿I U® (q 6PThose of you who aren’t quite sure whether to use GWorlds or the do-it-yourself ° d ONLN dI®U⁄ (qΔ
techniques ° d ONLN dU aß (} 6Smight want to skip ahead for a moment to “The GWorld Factor” just in case doing it ° d ONLN dnUßa⁄ (}≈ yourself is ° d ONLN dza m ◊ (â 6*a waste of time. In any case, it’s a good ° d ONLN d§a ◊m⁄ )ø5idea to read this whole Note because the concepts are ° d ONLN d⁄m y ; (ï 6mostly ° d ONLN d·m ;y⁄ )#Qthe same whether you’re using GWorlds or not. GWorlds just make the process a lot ° d ONLN d3y Ö… (° 6Ueasier, and they let you take advantage of the 8•24 GC video card. But, we’re not in ° d ONLN dày…Ö⁄ (°Áthat ° d ONLN dçÖ ë Ü (≠ 6section of the Note yet.
° d ONLN d∫ƒ – Ú *-Before you can tell QuickDraw to draw off of ° d ONLN dÁƒ Ú–⁄ )⁄1the screen, you’ll need to build three major data ° d ONLN d– ‹ V (¯ 6structures: a ,
Courier
° d ONLN d'– V‹ å )> CGrafPort
° d ONLN d0– å‹ ù )6, a
° d ONLN d4– ù‹ ¡ )PixMap
° d ONLN d:– ¡‹ Á )$, and a
° d ONLN dB– Á‹ )&GDevice
° d ONLN dI–‹ )*. ° d ONLN dK–‹! )Y ° d ONLN dL– ‹Q ) ou’ll also ° d ONLN dW–Q‹⁄ )1 need a couple of tables that ° d ONLN dt‹ ËV ( 6@define the colors involved with drawing to and copying from the ° d ONLN d¥‹VË⁄ (toff-screen image: the color ° d ONLN d–Ë Ù { ( 6table and the inverse ° d ONLN dÊË {Ù⁄ )cKtable. Of course, you’ll need the pixel image itself, which is often called ° d ONLN d 2Ù p ( 6the “pixel buffer” ° d ONLN d EÙ p ⁄ )XKor the “image buffer” or the “off-screen buffer” or just “the buffer.” It’s ° d ONLN d ë » (( 6\always called the “pixel image” in this Note. It doesn’t necessarily buffer anything anyway. ° d ONLN d Ó $ l *
The CGrafPort ° d ONLN d ¸0 < $ *A
° d ONLN d ˛0 $< Z ) CGrafPort
° d ONLN d
0 Z< ¬ )6 describes a drawing ° d ONLN d
0 ¬<™ )h/environment, and it’s the color version of the
° d ONLN d
K0™<⁄ )ËGrafPort
° d ONLN d
T< H e (d 6structure that’s ° d ONLN d
e< eHΩ )M?described on pages 147 through 155 in the QuickDraw chapter of ° d ONLN d
§<ΩH⁄ (d€Inside ° d ONLN d
´H T q (p 6Macintosh Volume ° d ONLN d
ªH qT t )Y ° d ONLN d
ºH tT⁄ )HI. The drawing environment consists of, among other things, the size and ° d ONLN d T ` ° (| 6 location of the graphics pen, ° d ONLN d #T °`⁄ )â=the foreground and background colors to use when something is ° d ONLN d a` lÖ (à 6Qdrawn, the pattern to use, the region to clip all drawing to, and the portion of ° d ONLN d ≤`Öl⁄ (à£a pixel image that ° d ONLN d ≈l x * (î 6the
° d ONLN d …l *x ` ) CGrafPort
° d ONLN d “l `x )6& logically exists in. Any initialized
lÅx⁄ )0 can be set as the ° d ONLN d x Ñ = († 6current ° d ONLN d (x =Ñ í )%port through the
° d ONLN d 9x íÑ ¬ )U_SetPort
° d ONLN d Ax ¬Ñ⁄ )0: routine. The current port is a set of parameters that are ° d ONLN d |Ñ ê Û (¨ 6-implicitly passed to most QuickDraw routines. ¡ 4¡˘
° d ONLN d ) < 5 ( Q Z)The most important reason to build a new ,
Courier
° d ONLN d ) ) 5A )œ CGrafPort
° d ONLN d 2 )A 5ß )6 when you draw off ° d ONLN d E )ß 5˛ )fscreen rather than ° d ONLN d X 5 < A í ( ] Zusing an existing
° d ONLN d j 5 í A » )V CGrafPort
° d ONLN d s 5 » Aë )6) is so that switching between drawing to ° d ONLN d ú 5ë A˛ )…an off-screen graphics ° d ONLN d ≥ A < MÉ ( i ZAenvironment and drawing to one or more windows (each of which is ° d ONLN d Ù AÉ M¿ ( i° an extended
° d ONLN d A¿ M )=GrafPort
° d ONLN d A M˛ )0 or
° d ONLN d M < Y r ( u Z CGrafPort
° d ONLN d M r Y )6% structure) on the screen is very eas ° d ONLN d: M Y )¶y ° d ONLN d; M Yü ). Some people use just one
° d ONLN dV Mü Y’ )Ç CGrafPort
° d ONLN d_ M’ Yÿ )6 ° d ONLN d` Mÿ Y˛ )to share ° d ONLN di Y < eß ( Å ZIbetween on-screen and off-screen graphics environments, and switch their
° d ONLN d≤ Yß eÀ ( Å≈PixMap
° d ONLN d∏ YÀ e˛ )$ structures ° d ONLN dƒ e < q æ ( ç Zto switch between drawing ° d ONLN dfi e æ q˙ )Ç@on screen and drawing off screen. That does work, but if the off ° d ONLN d e˙ q˛ ( ç- ° d ONLN d q < }T ( ô Z2screen and on-screen graphics environments have a ° d ONLN dQ qT }Ö ( ôr
different
° d ONLN d[ qÖ }Ø )1clipRgn
° d ONLN db qØ }º )*,
° d ONLN dd qº }‡ )
visRgn
° d ONLN dj q‡ }˛ )$, pen ° d ONLN dp } < â Ç ( • Zcharacteristic,
° d ONLN dÄ } Ç â ≤ )FportRect
° d ONLN dà } ≤ â∑ )08, or any other characteristics that are different, then ° d ONLN d¿ }∑ Ⲡ( •’
those must be ° d ONLN dŒ â < ï) ( ± Z3switched at that time too. If you instead create a
° d ONLN d â) ï_ )Ì CGrafPort
° d ONLN d
â_ ïÅ )6 that’s ° d ONLN d âÅ ï˛ )"dedicated to one graphics ° d ONLN d, ï < ° ‰ ( Ω Z#environment, then a simple call to
° d ONLN dO ï ‰ ° )®_SetPort
° d ONLN dW ï °˛ )01 effectively switches all these things for you at ° d ONLN dâ ° < ≠∫ ( … ZGonce. That’s why every window on the screen comes with its own port. A ° d ONLN d– °∫ ≠˛ ( …ÿsimple call to
° d ONLN dfl ≠ < π l ( ’ Z_SetPort
° d ONLN dÁ ≠ l π% )0& switches between the characteristics ° d ONLN d
≠% π˛ )π&of each window even if each window has ° d ONLN d4 π < ≈ ( · Z,radically different drawing characteristics. ° d ONLN da — < › Q *The
° d ONLN de — Q › á ) CGrafPort
° d ONLN dn — á › Ú )6 data structure is more ° d ONLN dÜ — Ú ›˛ )k5completely described in the “Color QuickDraw” chapter ° d ONLN dº › < È I ( Zof ° d ONLN dø › I È ù )
Inside Macintosh ° d ONLN d– › ù È • )TV ° d ONLN d— › § È )olume V, pages 49 ° d ONLN d„ › È˛ )\2through 52, and in the “Graphics Overview” chapter ° d ONLN d È < ı I ( Zof ° d ONLN d È I ı ù )
Inside Macintosh ° d ONLN d* È ù ı • )TV ° d ONLN d+ È § ı\ )$olume VI, pages 16-12 through 16-13. ° d ONLN dP <
Ä () Z
The PixMap ° d ONLN d[ <% ˜ *'A pixel image alone is just a formless ° d ONLN dÇ ˜%A )ª
blob of memor ° d ONLN dèA%G )Jy ° d ONLN dêF%⁄ ) . Pixel maps, defined by the
° d ONLN d≠⁄%˛ )îPixMap
° d ONLN d¥% <1 m (M Z structure, ° d ONLN dø% m1˛ )1Qdescribe pixel images, giving them a form and structure that’s suitable for Color ° d ONLN d1 <=d (Y Z4QuickDraw to draw into them and copy from them. The
° d ONLN dE1d=à (YÇPixMap
° d ONLN dK1à=Ω )$ structure ° d ONLN dV1Ω=˛ )5
tells you the ° d ONLN dd= <IK (e Z6dimensions and location in memory of the pixel image, ° d ONLN dö=KI˛ (ei$its coordinate system, and the depth ° d ONLN døI <U ¯ (q Z%and format of the pixels. Pixel maps ° d ONLN d‰I ¯U˛ )º5that describe indexed-color pixel images additionally ° d ONLN dU <aˆ (} Z^describe the colors that are represented by the values of the pixels in the pixel image. This ° d ONLN dxUˆa˛ (}is ° d ONLN d{a <m: (â Z6done through the color table, also known as the color ° d ONLN d±a:m˛ )˛'look-up table or CLUT. Color tables are ° d ONLN dŸm <y Á (ï Z%attached to pixel maps through their
° d ONLN d˛m Áy )´pmTable
° d ONLN dmyk )* field. Direct-color ° d ONLN dmky˛ )Z pixel images have pixel values ° d ONLN d9y <Öô (° ZLthat describe their own colors, and so color tables aren’t needed for those. ° d ONLN dÜë <ù S *The
aÒ˝˛ )3structure, describe color environments. They’re the ° d ONLN d
ï˝ < ’ (% ZTmost misunderstood data structure when it comes to off-screen graphics environments ° d ONLN d
È˝’ ˛ (%Û for three ° d ONLN d
Û <U (1 Z;major reasons: first, they’re not originally documented as ° d ONLN d . U˛ (1s!being relevant to humans; second, ° d ONLN d P <!i (= ZBthey look as though they’re only for screens; and third, it looks ° d ONLN d íi!˛ (=á as though color tables describe ° d ONLN d ≤! <- ƒ (I Zcolor environments. We can ° d ONLN d Õ! ƒ-˛ )à?dispose of these myths here: graphics devices are documented as ° d ONLN d
- <9Ì (U Z`being useful to humanity in this Note at least; they’re critically important for both on-screen ° d ONLN d m-Ì9˛ (U and ° d ONLN d q9 <E1 (a Z.off-screen drawing; and color tables describe ° d ONLN d ü91EŒ )ı the colors in pixel images, ° d ONLN d ª9ŒE› )ùnot ° d ONLN d æ9›E˛ ) color ° d ONLN d ≈E <Q Ä (m Z
environments. ° d ONLN d ”] <i/ *2What’s all this about color environments? In theor ° d ONLN d
]/i5 )Ûy ° d ONLN d
]4i< ), ° d ONLN d
]<i˛ )*there are virtually three hundred trillion ° d ONLN d
3i <uW (ë Z9colors available with Color QuickDraw through the 48-bit
° d ONLN d
liWuá (ëuRGBColor
° d ONLN d
tiáuŸ )0 record. In realit ° d ONLN d
ÜiŸufl )Ry ° d ONLN d
áifiu˛ ), there ° d ONLN d
èu <ÅC (ù Z8are never this many colors available, and in fact there ° d ONLN d
«uCÅ˛ (ùa"might be only two. Color QuickDraw ° d ONLN d
° d ONLN d )O *@current color environment. This can be done with a color table, ° d ONLN d @ O )⁄ ( Em but that’s not very efficient. ° d ONLN d _ ) 5 @ ( Q 6Finding ° d ONLN d g ) @ 5 € )("the closest available color to an ,
Courier
° d ONLN d â ) € 5 )õRGBColor
° d ONLN d ë ) 5⁄ )0, in a color table means searching the entire ° d ONLN d æ 5 A q ( ] 6color table for that ° d ONLN d ” 5 q A⁄ )YKone closest color. If that’s done just once, then performance isn’t much of ° d ONLN d A MS ( i 6Dan issue, but if it’s done many times, the performance hit could be ° d ONLN dc AS M⁄ ( iq significant. A very bad case ° d ONLN dÄ M Y D ( u 6 of this is
° d ONLN dã M D Y z ), _CopyBits
° d ONLN dî M z Yé )6;, where every pixel value in the source image is converted ° d ONLN dœ Mé Y™ ( u¨to an
° d ONLN d’ M™ Y⁄ ) RGBColor
° d ONLN dfi Y e ( Å 62by looking it up in the color table of the source
° d ONLN d Y e& )ÍPixMap
° d ONLN d Y& e: )$. If ° d ONLN d Y: e⁄ )"the color table of the destination
° d ONLN d> e q < ( ç 6PixMap
° d ONLN dD e < qª )$O had to be searched to find the closest available color for every pixel in the ° d ONLN dì eª q⁄ ( çŸsource
° d ONLN dö q } < ( ô 6PixMap
° d ONLN d† q < } ∂ )$, then the performance of ° d ONLN d∫ q ∂ }J )z even the most straightforward
° d ONLN dÿ qJ }Ä )î _CopyBits
° d ONLN d· qÄ }⁄ )6 call could be a lot ° d ONLN dˆ } â â ( • 6slower than it has to be. ° d ONLN d ï ° fl *+To avoid this performance hit, the current
° d ONLN d; ï fl ° )«GDevice
° d ONLN dB ï °F )*
provides an ° d ONLN dO ïF °⁄ )= inverse table and a device type ° d ONLN do ° ≠å ( … 6Lwhich are used to determine the available set of colors. Inverse tables are ° d ONLN dª °å ≠⁄ ( …™anticolor tables. ° d ONLN dÕ ≠ π € ( ’ 6(Where color tables give you a color for ° d ONLN dı ≠ € π⁄ )√4a given pixel value, inverse tables give you a pixel ° d ONLN d* π ≈ ‚ ( · 6+value for a given color. Every conceivable ° d ONLN dU π ‚ ≈⁄ ) 3color table has a corresponding conceivable inverse ° d ONLN dâ ≈ —B ( Ì 6>table, just as every positive real number has a corresponding ° d ONLN d« ≈B —⁄ ( Ì` negative real number, or every ° d ONLN dÊ — ›m ( ˘ 6BMr. Spock has a corresponding Mr. Spock with a goatee. The device ° d ONLN d( —m ›⁄ ( ˘ãtype specifies whether ° d ONLN d? › È Û ( 6.the color environment uses the indexed-color, ° d ONLN dm › Û È÷ )€1fixed-color, or direct-color model. In the direct ° d ONLN dû ›÷ È⁄ )„- ° d ONLN dü È ı k ( 6color model, the ° d ONLN d∞ È k ı — )Sinverse table is empt ° d ONLN d≈ È — ı ◊ )fy ° d ONLN dΔ È ÷ ı⁄ )4. Only the indexed-color and direct-color models are ° d ONLN d˚ ı É ( 6described in this Note. ° d ONLN d
p *@When you specify a color in an indexed-color environment, Color ° d ONLN dS
p⁄ (5éQuickDraw takes the
° d ONLN dg % H (A 6RGBColor
° d ONLN do H%ê )0I specification and converts it into a value that can be used as an index ° d ONLN d∏ê%⁄ (AÆinto the inverse ° d ONLN d…% 1 { (M 6table of the current
ONLN f ` ° d $MOR2 8 ◊ û ‡= q &T ¢aEaEa ¢^ ¢^BTBTEaE ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1Q ü^B ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ û ‡ ß ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R †] ´ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ ® ‡ ± ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R ™] µ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ ≤ ‡ ª ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R ¥] ø ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ º ‡ ≈ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R æ] … ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ Δ ‡ œ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R »] ” ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ – ‡ Ÿ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R “] › ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ ⁄ ‡ „ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R ‹] Á ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ ‰ ‡ Ì ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1R Ê] Ò ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ Ó ‡ ˜ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R ] ˚ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ ¯ ‡ ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1R ˙] ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ ‡ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R] ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ ‡ ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1R] ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ ‡ ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1R]# ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊ ‡) ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R"]- ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊* ‡3 ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1R,]7 ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ◊4 ‡= ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1R6]A ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 X π9 ‘9 ˇˇ † å q F8P@P<F@F8P< "4; † ç ° d MOR2 ° d $MOR2 X π. ‘. ˇˇ † å q F-P5P1F5F-P1 "40 † ç ° d MOR2 ° d $MOR2 X π$ ‘$ ˇˇ † å q F#P+P'F+F#P' "4& † ç ° d MOR2 ° d $MOR2 X π ‘ ˇˇ † å q FP!P F!FP "4 † ç ° d MOR2 ° d $MOR2 X ó ‘ ˇˇ † å q FPPFFP " 9 † ç ° d MOR2 ° d $MOR2 X ó ‘ ˇˇ † å q FP
P F
FP " 9 † ç ° d MOR2 ° d $MOR2 X ó ¸ ‘ ¸ ˇˇ † å q F ˚PP ˇFF ˚P ˇ " ˛ 9 † ç ° d MOR2 ° d $MOR2 X ó Ú ‘ Ú ˇˇ † å q F ÒP ˘P ıF ˘F ÒP ı " Ù 9 † ç ° d MOR2 ° d $MOR2 X r Ë ‘ Ë ˇˇ † å q F ÁP ÔP ÎF ÔF ÁP Î "Ì Í ^ † ç ° d MOR2 ° d $MOR2 X r fi ‘ fi ˇˇ † å q F ›P ÂP ·F ÂF ›P · "Ì ‡ ^ † ç ° d MOR2 ° d $MOR2 X r ‘ ‘ ‘ ˇˇ † å q F ”P €P ◊F €F ”P ◊ "Ì ÷ ^ † ç ° d MOR2 ° d $MOR2 X r ‘ ˇˇ † å q F …P —P ÕF —F …P Õ "Ì Ã ^ † ç ° d MOR2 ° ñ † ò ˇˇˇˇˇˇ
‘‡, ç• ç• ° d ONLN dˇˇ +‹red † ô † ó ° d $MOR2 8 f Δ oe
‘ DaÈ q &„ mm Ì Ìj„j„mm ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1‡ «Ìj ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f Δ o œ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1· »Ï ” ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f – o Ÿ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1· “Ï › ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f ⁄ o „ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1· ‹Ï Á ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f ‰ o Ì ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1· ÊÏ Ò ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f Ó o ˜ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1· Ï ˚ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f ¯ o ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1· ˙Ï ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f o ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1·Ï ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f o ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1·Ï ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f o ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1·Ï# ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f o) ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1·"Ï- ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f* o3 ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1·,Ï7 ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f4 o= ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1·6ÏA ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f> oG ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1·@ÏK ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 fH oQ ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1·JÏU ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 fR o[ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1·TÏ_ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 f\ oe ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1·^Ïi ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä Ó ìç q & Úïï Ú Úííïï ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1 Ôí ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä Ó ì ˜ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1 ˚ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä ¯ ì ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1 ˙ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä ì ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1 ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä ì ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1 ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä ì ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1# ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä ì) ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1"- ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä* ì3 ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1,7 ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä4 ì= ˇˇˇˇˇˇ ˇˇˇˇˇˇ 16A ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä> ìG ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1@K ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 äH ìQ ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1JU ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 äR ì[ ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1T_ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ä\ ìe ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1^i ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 äf ìo ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1hs ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 äp ìy ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1r} ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 äz ìÉ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1|á ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 äÑ ìç ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1Üë ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° ñ † ò ˇˇˇˇˇˇ
¯0T ° d ONLN dˇˇ +#$green † ô † ó ° ñ † ò
X'| ° d ONLN dˇˇ ++#blue † ô † ó ° d $MOR2 8 ≠ ∂µ
‘ DaÈ q &*7Ω7Ω744∫*∫*Ω7Ω ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1'4∫ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠ ∂ ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1(3# ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠ ∂) ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1("3- ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠* ∂3 ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1(,37 ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠4 ∂= ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1(63A ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠> ∂G ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1(@3K ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠H ∂Q ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1(J3U ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠R ∂[ ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1(T3_ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠\ ∂e ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1(^3i ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠f ∂o ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1(h3s ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠p ∂y ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1(r3} ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠z ∂É ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1(|3á ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠Ñ ∂ç ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1(Ü3ë ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠é ∂ó ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1(ê3õ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠ò ∂° ü˚ü˚ü˚ ü˚ü˚ü˚ U"UàUUà 1(ö3• ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠¢ ∂´ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1(§3Ø ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° d $MOR2 8 ≠¨ ∂µ ˇˇˇˇˇˇ ˇˇˇˇˇˇ 1(Æ3π ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° ñ † ò ˇˇˇˇˇˇ
·nÌì ° d ONLN dˇˇ (Ín=$1234 † ô † ó ° ñ † ò
ñª ° d ONLN dˇˇ +($=$5678 † ô † ó ° ñ † ò
(æ4È ° d ONLN dˇˇ +(#=$9ABC † ô † ó ° ñ † ò
RF^k ° d ONLN dˇˇ ([F=$0159 † ô † ó ° ñ † ò
N ü
° d ONLN dˇˇ ( NRGBColor
° d ONLN dˇˇ )0 record † ô † ó ° ñ † ò
Ÿ ú9
` ° d ONLN dˇˇ + { † ô † ó ° ñ † ò
R D^ ù
° d ONLN dˇˇ ([ DInverse table index † ô † ó † ƒ ° d
ONLN f .
IR ° d ONLN d
óZ <f∂ +'>Figure 1 Conversion of RGBColor Record to Inverse-Table Index ° d ONLN d
÷r ~ ∂ (ö 6 The same process is used when
° d ONLN d
Ùr ∂~ Ï )û _CopyBits
° d ONLN d
˝r Ï~√ )6. is called with an indexed-color destination. ° d ONLN d +r√~⁄ )◊Each ° d ONLN d 0~ ä µ (¶ 6#pixel in the source pixel image is ° d ONLN d S~ µä )ùconverted to an
° d ONLN d c~ä3 )NRGBColor
° d ONLN d k~3ä⁄ )0# either by doing a table look-up of ° d ONLN d èä ñΩ (≤ 6Rthe source pixel map’s color table if the source pixel image uses indexed colors, ° d ONLN d ·äΩñ⁄ (≤€or by ¡ 4¡˘
(÷ 64 ) of 51 )Á2QD 13 - Principia Off-Screen Graphics Environments +nM.QD.PrincipiaOffScreen ˇ ° ¿ bu
/M_pd where{pop}{ ° ¿#userdict begin
/M_d{M_pd begin}bind def/M_pd dup 24 dict def
end load begin
/bdf{bind def}bind def/xdf{exch def}bdf
/mtx matrix def/M_M matrix def/M_Q matrix def/pop4{pop pop pop pop}bdf
/M_n{gsave M_Q currentmatrix pop M_M astore aload setmatrix newpath}bdf/M_q{M_Q setmatrix}bdf
° d ONLN d < ) Å ( E Zexpanding the ° d ONLN d Å ) ’ )Epixel value to an ,
Courier
° d ONLN d ’ ) )TRGBColor
° d ONLN d ( )˛ )05 record if the source pixel image uses direct colors. ° d ONLN d ^ ) < 5 } ( Q ZThe resulting
° d ONLN d l ) } 5 ≠ )ARGBColor
° d ONLN d t ) ≠ 5& )0 is then used to look up a ° d ONLN d è )& 5˛ )y/pixel value in the inverse table of the current
° d ONLN d ø 5 < A f ( ] ZGDevice
° d ONLN d Δ 5 f A~ )*?, and this pixel value is put into the destination pixel image. ° d ONLN d M < Y Å ( u ZIf you specify ° d ONLN d M Å Yê )E:a color in a direct-color environment, then the resulting
° d ONLN dO Mê Y¿ ( uÆRGBColor
° d ONLN dW M¿ Y˛ )0
is converted ° d ONLN de Y < e R ( Å Zto a ° d ONLN dj Y R e˛ )Tdirect pixel value by the processes that are shown on pages 17-6 through 17-9 of the ° d ONLN dø e < q œ ( ç Z “Color QuickDraw” chapter of ° d ONLN d‹ e œ q# )ìInside Macintosh ° d ONLN dÌ e# q+ )TV ° d ONLN dÓ e* qZ ) olume VI. ° d ONLN d¯ } < â [ ( • ZUsuall ° d ONLN d˛ } [ â a ) y ° d ONLN dˇ } ` âK )2, inverse-table look-up involves an extra step to ° d ONLN d1 }K Ⲡ)Î$find what are called “hidden colors” ° d ONLN dV â < ïz ( ± ZFusing proprietary information that’s stored at the end of the inverse ° d ONLN dú âz ï˛ ( ±ò table. With an inverse-table ° d ONLN dπ ï < °à ( Ω ZFresolution of four, only 16 shades of any particular component can be ° d ONLN dˇ ïà °˛ ( Ω¶distinguished, and that’s ° d ONLN d ° < ≠
( … Z*often not enough. An inverse table with a ° d ONLN dC °
≠˛ )Œ4resolution of five is much larger, but it still only ° d ONLN dx ≠ < π! ( ’ Z-gives you 32 shades of any component. Hidden ° d ONLN d• ≠! π˙ )Â-colors are looked up after the normal inverse ° d ONLN d“ ≠˙ π˛ )Ÿ- ° d ONLN d” π < ≈ â ( · Ztable look-up to ° d ONLN d‰ π â ≈˛ )MNgive a much more accurate representation of the specified color in the current ° d ONLN d3 ≈ < — ¸ ( Ì Z)color environment than the inverse-table ° d ONLN d\ ≈ ¸ —˛ )¿2look-up alone can produce. Sometimes, most notably ° d ONLN dè — < ›s ( ˘ Z?when the arithmetic transfer modes are used or if dithering is ° d ONLN dŒ —s ›˛ ( ˘ëused, the hidden colors are ° d ONLN dÍ › < È d ( Zignored. ° d ONLN dÛ ı < *(When a new color table is assigned to a
° d ONLN d ı& )ΔPixMap
° d ONLN d! ı&– )$% or when its existing color table is ° d ONLN dF ı–˛ )™ modified, ° d ONLN dP <
! () Z.then a new corresponding inverse table should ° d ONLN d~!
â )Âbe generated for the
° d ONLN dìâ
≥ )hGDevice
° d ONLN dö≥
˛ )* that’ll be used ° d ONLN d´
< (5 Z+when drawing into that environment. Normall ° d ONLN d÷
ONLN f ` ° d $MOR2 8 H Z ¢ ¥ q & O h ≠ Δ ≠ Δ ≠ h ™ h ™ √ O √ O Δ ≠ Δ fl˙fl˙fl˙ fl˙fl˙fl˙ à à " 1 L e ™ √ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° ñ † ò ˇˇˇˇˇˇ
< p H ∏ ,
Courier
Ôc Ôc ° d ONLN dˇˇ +: CGrafPort † ô † ó ° d $MOR2 8 H Î ¢C
< e+» q & O ˘ ≠U ≠U ≠ ˘ ™ ˘ ™R OR OU ≠U fl˙fl˙fl˙ fl˙fl˙fl˙ à à " 1 L ˆ ™R ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° ñ † ò ˇˇˇˇˇˇ
< H@ ° d ONLN dˇˇ )òGDevice † ô † ó ° d $MOR2 8 Δ § ¸
< e+» q & Õ ≤+++ ≤( ≤( Õ Õ+ fl˙fl˙fl˙ fl˙fl˙fl˙ à à " 1 Ø( ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° ñ † ò ˇˇˇˇˇˇ
∫ ≈ Δ ı ° d ONLN dˇˇ ( ƒ ≈PixMap † ô † ó ° d $MOR2 8 Z d f ™ ˇˇˇˇˇˇ
< e+» 1 ` q l ∑ ° d MOR2 ° ñ † ò
` q l ∑ ° d ONLN dˇˇ ( j q
portPixMap † ô † ó ° d $MOR2 8 Z ˚ f3 ˇˇˇˇˇˇ
< e+» 1 ` l@ ° d MOR2 ° ñ † ò
` l@ ° d ONLN dˇˇ )ógdITable † ô † ó ° d $MOR2 8 ~ ä, ˇˇˇˇˇˇ
< e+» 1 Ñ ê9 ° d MOR2 ° ñ † ò
Ñ ê9 ° d ONLN dˇˇ +$gdPMap † ô † ó ° d $MOR2 8 ∏ È ˇˇˇˇˇˇ
< e+» 1 ≈ ˆ ° d MOR2 ° ñ † ò
≈ ˆ ° d ONLN dˇˇ ( ≈pmTable † ô † ó ° d $MOR2 X ` Æ ` ƒ ˇˇ
< e+» ˇˇˇˇˇˇˇˇ " e ∫ ° d MOR2 ° d $MOR2 X ` ƒ ∞ ƒ ˇˇ † å q ¨ Õ ∂ ’ ∂ — ¨ ’ ¨ Õ ∂ — # L † ç ° d MOR2 ° d $MOR2 X Ñ ˘ Ñ ⁄ ˇˇ " â· ° d MOR2 ° d $MOR2 X Ñ ⁄ ∞ ⁄ ˇˇ † å q ¨ „ ∂ Î ∂ Á ¨ Î ¨ „ ∂ Á # ( † ç ° d MOR2 ° d $MOR2 8 V^ j∂ q & ]l u» u» ul rl r≈ ]≈ ]» u» fl˙fl˙fl˙ fl˙fl˙fl˙ à à " 1 Zi r≈ ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° ñ † ò ˇˇˇˇˇˇ
Jq Væ ° d ONLN dˇˇ ( Sq
Inverse Table † ô † ó ° d $MOR2 X `5 `Z ˇˇ † å
< e+» q b] jg fg b] j] fg " eA! † ç ° d MOR2 ° d $MOR2 8 m q &#(((#%#%||( fl˙fl˙fl˙ fl˙fl˙fl˙ à à " 1
%| ˇˇˇˇˇˇˇˇ 8 ° d MOR2 ° ñ † ò ˇˇˇˇˇˇ
˝- p ° d ONLN dˇˇ (- Color Table † ô † ó ° d $MOR2 X Î ˇˇ † å
< e+» q " ˜! † ç ° d MOR2 † ƒ ° d
ONLN f . ˇˇˇˇˇˇ
IR ° d ONLN d $ 80∫ (L VAFigure 2 Relationships Between Structures for Off-Screen Drawing ° d ONLN d B< H — (d 6)Notice that there’s no way to get to the
° d ONLN d k< —H ˚ )πGDevice
° d ONLN d r< ˚H) )*
from the
° d ONLN d |<)H_ ). CGrafPort
° d ONLN d Ö<_Hû )6, nor is there ° d ONLN d î<ûH⁄ )? a way to get ° d ONLN d °H T 5 (p 6to the
° d ONLN d ®H 5T k ) CGrafPort
° d ONLN d ±H kT ô )6
from the
° d ONLN d ªH ôT √ ).GDevice
° d ONLN d ¬H √T ˇ )*
, though the
° d ONLN d œH ˇT# )<PixMap
° d ONLN d ’H#T√ )$" can be found through either one. ° d ONLN d ˜H√TÀ )†Y ° d ONLN d ¯H T⁄ )our ° d ONLN d ¸T ` — (| 6(application must keep track of both the
° d ONLN d$T —` )π CGrafPort
° d ONLN d-T`/ )6 and the
° d ONLN d6T/`Y )(GDevice
° d ONLN d=TY`] )*.
° d ONLN d?x á õ (£ 6Building the Blocks
° d ONLN dSì ü T *
As with just ° d ONLN d`ì Tü⁄ )<Qabout any algorithm, there are many ways to put the different structures together ° d ONLN d≤ü ´8 (« 6;that form an off-screen graphics environment. This section ° d ONLN dÌü8´⁄ («V covers just one way to build the ° d ONLN d´ ∑ … (” 6&architecture that’s shown in Figure 2. ° d ONLN d5√ œ ù *Building the CGrafPort ° d ONLN dL€ Á . *The
° d ONLN dP€ .Á d ) CGrafPort
° d ONLN dY€ dÁ ° )6 structure is ° d ONLN dg€ °Áx )=,the easiest one to put together because the
° d ONLN dì€xÁ¥ )◊
_OpenCPort
° d ONLN dù€¥Á⁄ )< routine ° d ONLN d¶Á Û € ( 6)initializes so many of the fields of the
° d ONLN dœÁ €Û )√ CGrafPort
° d ONLN dÿÁÛ )6 ° d ONLN dŸÁÛ⁄ )(structure for you. It also allocates and ° d ONLN dÛ ˇ ( 66initializes the structures that are attached to every
° d ONLN d8Ûˇ> ) CGrafPort
° d ONLN dAÛ>ˇÄ )6, such as the
° d ONLN dOÛġ§ )BvisRgn
° d ONLN dUÛ§ˇ¨ )$,
° d ONLN dWÛ¨ˇ÷ )clipRgn
° d ONLN d^Û÷ˇ⁄ )*,
° d ONLN d`ˇ H (' 6grafVars
° d ONLN dhˇ H )0) handle, and so forth. Most of these are ° d ONLN dëˇ ⁄ )œ)initialized with values that are fine for ° d ONLN dª í (3 6general purposes, but the
° d ONLN d’ í ∂ )zvisRgn
° d ONLN d€ ∂ Ω )$,
° d ONLN d› Ω Á )clipRgn
° d ONLN d‰ Á Ó )*, ° d ONLN dÊ Ó )and
° d ONLN dÍ 3 )portRect
° d ONLN dÚ 3⁄ )0$ fields should be set to the desired ° d ONLN d # ˜ (? 6.boundary rectangle of the off-screen graphics ° d ONLN dE ˜#⁄ )fl+environment. What follows is an overview of ° d ONLN dq# /) (K 65each of the fields that you have to worry about when ° d ONLN d¶#)/ê (KGyou’re setting up a
° d ONLN d∫#ê/Δ )g CGrafPort
° d ONLN d√#Δ/⁄ )6 for ° d ONLN d»/ ; u (W 6drawing off screen.
° d ONLN d‹G S T *
portPixMap
° d ONLN dÁG ÑS ˙ )lhandle to the off-screen
° d ONLN d G ˙S )vPixMap
° d ONLN dG S& )$.
° d ONLN dG&Sb )
_OpenCPort
° d ONLN dGbSf )< ° d ONLN dGfS⁄ )initializes this field to a ° d ONLN d/S Ñ_ ≠ ({ ¢copy of ° d ONLN d7S ≠_ ¿ ))the
° d ONLN d;S ¿_ ‰ )PixMap
° d ONLN dAS ‰_T )$ that’s attached to the
° d ONLN dYST_x )pgdPMap
° d ONLN d_Sx_⁄ )$ field of the current
° d ONLN du_ Ñk Æ (á ¢GDevice
° d ONLN d|_ ÆkG )*!. An overview of setting up this
° d ONLN dù_Gkk )ôPixMap
° d ONLN d£_kk )$ for ° d ONLN d®_k⁄ )drawing off screen ° d ONLN dªk Ñw| (ì ¢6is given in “Building the PixMap” later in this Note.
° d ONLN dÚw É H (ü 6portRect
° d ONLN d˚w ÑÉ ≤ )l
specifies ° d ONLN dw ≤É⁄ ).<the rectangular area of the associated pixel image that this
° d ONLN dBÉ Ñè ∫ (´ ¢ CGrafPort
° d ONLN dKÉ ∫è Ω )6 ° d ONLN dLÉ Ωè⁄ )=controls. This field should be set to the desired rectangular ¡ 4¡˘
(÷ 66 ) of 51 )Á2QD 13 - Principia Off-Screen Graphics Environments +nM.QD.PrincipiaOffScreen ˇ ° ¿ bu
/M_pd where{pop}{ ° ¿#userdict begin
/M_d{M_pd begin}bind def/M_pd dup 24 dict def
end load begin
/bdf{bind def}bind def/xdf{exch def}bdf
/mtx matrix def/M_M matrix def/M_Q matrix def/pop4{pop pop pop pop}bdf
/M_n{gsave M_Q currentmatrix pop M_M astore aload setmatrix newpath}bdf/M_q{M_Q setmatrix}bdf
° d ONLN d ® ) ø ( E Δarea ° d ONLN d ø )a ) of the off-screen image because ,
Courier
° d ONLN d % a )ù )¢
_OpenCPort
° d ONLN d / ù )˛ )< doesn’t necessarily ° d ONLN d D ) ® 5 € ( Q Δinitialize it ° d ONLN d R ) € 56 )3to this size. Usuall ° d ONLN d f )6 5< )[y ° d ONLN d g ); 5˛ )+, the top-left corner of this rectangle has ° d ONLN d ì 5 ® A~ ( ] Δ/the coordinates (0, 0), but not necessarily so.
° d ONLN d √ A < M ` ( i ZvisRgn
° d ONLN d A ® M! )lhandle to the region that ° d ONLN d ‰ A! M˛ )y-specifies the visible area into which you can ° d ONLN d M ® Y « ( u Δdraw.
° d ONLN d M « Y )
_OpenCPort
° d ONLN d" M Yç )< doesn’t necessarily initialize ° d ONLN dB Mç Y˙ )äit to the size of the off ° d ONLN d[ M˙ Y˛ )m- ° d ONLN d\ Y ® ea ( Å Δ)screen image, so it should be set to the ° d ONLN dÖ Ya e˛ )π same size and coordinates as the
° d ONLN d¶ e ® q ÿ ( ç ΔportRect
° d ONLN dÆ e ÿ qæ )00 and left at that. This field is more important ° d ONLN dfi eæ q˛ )Ê for windows ° d ONLN dÍ q ® }Ø ( ô Δ5because parts of them can be hidden by other windows.
° d ONLN d } < â f ( • ZclipRgn
° d ONLN d( } ® â! )lhandle to the region that ° d ONLN dB }! Ⲡ)y-specifies the logical area into which you can ° d ONLN dp â ® ï ∑ ( ± Δdra ° d ONLN ds â ∑ ï ¿ )w ° d ONLN dt â ø ï Δ ).
° d ONLN dv â Δ ï )
_OpenCPort
° d ONLN dÄ â ïÕ )<. initializes it to cover the entire QuickDraw ° d ONLN dÆ âÕ ï˛ )À
coordinate ° d ONLN dπ ï ® °# ( Ω Δplane. It’s usually a good ° d ONLN d‘ ï# °˛ ){/idea to set it to the same size and coordinates ° d ONLN d ° ® ≠ Œ ( … Δas the
° d ONLN d ° Œ ≠ ˛ )&portRect
° d ONLN d ° ˛ ≠w )0 to avoid problems if ° d ONLN d) °w ≠ç )ythe
° d ONLN d- °ç ≠∑ )clipRgn
° d ONLN d4 °∑ ≠˛ )*
is scaled or ° d ONLN dB ≠ ® πÌ ( ’ ΔDtranslated, which causes its signed integer coordinates to overflow ° d ONLN dÜ ≠Ì π˛ ( ’ and ° d ONLN dä π ® ≈› ( · Δ;turn it into an empty region. One of the most common cases ° d ONLN d≈ π› ≈˛ ( ·˚of this ° d ONLN dÕ ≈ ® —{ ( Ì Δ-occurs when a picture that’s created in this
° d ONLN d˙ ≈{ —± )” CGrafPort
° d ONLN d ≈± —˘ )6 is drawn into ° d ONLN d ≈˘ —˛ )Ha ° d ONLN d — ® ›» ( ˘ Δ@destination rectangle that’s any larger than or translated from ° d ONLN dT —» ›˛ ( ˘Ê the original ° d ONLN da › ® ÈŒ ( Δ=picture frame. Everything in the picture, including the clip ° d ONLN dû ›Œ È˛ (Ï
¡ )r"clip region becomes logically empt ° d ONLN dx¡
« )ßy ° d ONLN dyΔ
˛ ) . The result ° d ONLN dÜ
® (5 Δis that nothing is drawn. ° d ONLN d†% <1˘ (M Z[The CreateOffScreen routine in Listing 1 creates an off-screen graphics environment, given ° d ONLN d˚%˘1˛ (Ma ° d ONLN d˝1 <=J (Y Z9boundary rectangle, pixel depth, and color table, and it ° d ONLN d61J=» (Yhreturns a new off-screen
° d ONLN dO1»=˛ )~ CGrafPort
° d ONLN dY= <I P (e Zand
° d ONLN d]= PI z )GDevice
° d ONLN dd= zIû )*@, along with an error code. The desired pixel depth in bits per ° d ONLN d§=ûI˛ (eºpixel is given in the
° d ONLN d∫I <U Z (q Zdepth
° d ONLN døI ZU æ ) parameter. If the ° d ONLN d“I æU˛ )d<pixel depth is eight or less, then an indexed-color graphics ° d ONLN dU <a. (} Z5environment is created and a color table is required ° d ONLN dDU.aM )Úin the
° d ONLN dKUMaq ) colors
° d ONLN dQUqa˛ )$ parameter. If the pixel depth ° d ONLN dpa <m4 (â Z0is 16 or 32 bits per pixel and 32-Bit QuickDraw ° d ONLN d†a4m˛ )¯*is available, then a direct-color graphics ° d ONLN dÀm <y › (ï Z environment is created and the
K bytesPerRow := ((depth * (bounds.right - bounds.left) + 31) DIV 32) * 4; ° d ONLN dÔ « “ Í ** (* Get the current QuickDraw version *) ° d ONLN d — ‹0 *
8 error := Gestalt(gestaltQuickdrawVersion, qdVersion); ° d ONLN dS € Ê r *
error := noErr; ° d ONLN df Ô ˙û *N (* Make sure depth is indexed or depth is direct and 32-Bit QD installed *) ° d ONLN dµ ˘ ] *
A IF (depth = 1) OR (depth = 2) OR (depth = 4) OR (depth = 8) OR ° d ONLN d˜ ® *
P (((depth = 16) OR (depth = 32)) AND (qdVersion >= gestalt32BitQD)) THEN ° d ONLN dH
O *
BEGIN ° d ONLN dT "® *
P (* Maximum number of bytes per row is 16,382; make sure within range *) ° d ONLN d•! , Ù *
, IF bytesPerRow <= kMaxRowBytes THEN ° d ONLN d“+ 6 m *
BEGIN ° d ONLN d‰5 @® *
P (* Make sure a color table is provided if the depth is indexed *) ° d ONLN d5? J Ω *
! IF depth <= 8 THEN ° d ONLN dWI T ÷ *
& IF colors = NIL THEN ° d ONLN d~S ^î *
L (* Indexed depth and clut is NIL; is parameter error *) ° d ONLN dÀ] h € *
' error := paramErr; ° d ONLN dÛg r c *
END ° d ONLN dq | Y *
ELSE ° d ONLN d{ Üî *
L (* # of bytes per row is more than 16,382; is parameter error *) ° d ONLN d^Ö ê Æ *
error := paramErr; ° d ONLN d}è ö E *
END ° d ONLN dáô § ; *
ELSE ° d ONLN dè£ Æ+ *
7 (* Pixel depth isn’t valid; is parameter error *) ° d ONLN d«≠ ∏ ê *
error := paramErr; ° d ONLN d‡¡ ÃX *@ (* If sanity checks succeed, then allocate a new CGrafPort *) ° d ONLN d!À ÷ ê *
= (* Grab the initialized PixMap handle *) ° d ONLN d V 1 < <J *
6 newPixMap := newPort^.portPixMap; ° d ONLN d ç E < P| *@ (* Allocate and initialize a new GDevice *) ° d ONLN d Œ O < ZÜ *
B error := CreateGDevice(newPixMap, newDevice); ° d ONLN d Y < d ™ *
END; ° d ONLN d( m < x *+ (* Restore the saved port *) ° d ONLN dT w < Ç Ê *
" SetPort(savedPort); ° d ONLN dw Å < å á *
END ° d ONLN dá ã < ñ } *
ELSE ° d ONLN dï ï < † “ *
error := MemError; ° d ONLN d¥ ü < ™ n *
END; ° d ONLN dø ≥ < æ; *3 (* Restore the given state of the color table *) ° d ONLN dÛ Ω < » ¥ *
IF colors <> NIL THEN ° d ONLN d « < “ *
, HSetState(Handle(colors), savedState); ° d ONLN d9 € < ÊE *5 (* One Last Look Around The House Before We Go… *) ° d ONLN do  < π *
IF error <> noErr THEN ° d ONLN dâ Ô < ˙ s *
BEGIN ° d ONLN dï ˘ <ö *
F (* Some error occurred; dispose of everything we allocated *) ° d ONLN d‹ < · *
! IF newPixMap <> NIL THEN ° d ONLN d˛
< ë *
BEGIN ° d ONLN d <"1 *
1 DisposCTable(newPixMap^^.pmTable); ° d ONLN dB! <,' *
/ DisposPtr(newPixMap^^.baseAddr); ° d ONLN dr+ <6 å *
END; ° d ONLN dÉ5 <@ · *
! IF newDevice <> NIL THEN ° d ONLN d•? <J ë *
BEGIN ° d ONLN d∑I <T^ *
: DisposHandle(Handle(newDevice^^.gdITable)); ° d ONLN dÚS <^' *
/ DisposHandle(Handle(newDevice)); ° d ONLN d"] <h å *
END; ° d ONLN d3g <r ◊ *
IF newPort <> NIL THEN ° d ONLN dSq <| ë *
BEGIN ° d ONLN de{ <Ü Î *
# CloseCPort(newPort); ° d ONLN dâÖ <ê ˇ *
' DisposPtr(Ptr(newPort)); ° d ONLN d±è <ö å *
END; ° d ONLN d¬ô <§ i *
END ° d ONLN dã <Æ _ *
ELSE ° d ONLN d‘≠ <∏ s *
BEGIN ° d ONLN d‡∑ <¬« *
O (* Everything’s OK; return refs to off-screen CGrafPort and GDevice *) ° d ONLN d0¡ <Ã » *
retPort := newPort; ° d ONLN dMÀ <÷ · *
! retGDevice := newDevice; ° d ONLN do’ <‡ n *
END; ° d ONLN dzfl <Í » *
CreateOffScreen := error; ° d ONLN dóÈ <Ù P *
END;
° d ONLN dúˇ < ü *MPW C Listing 1
° d ONLN d¨ <"∏ *L#define kMaxRowBytes 0x3FFE /* Maximum number of bytes in a row of pixels */ ° d ONLN d˘+ <6 ™ *OSErr CreateOffScreen( ° d ONLN d5 <@Ü *
B Rect *bounds, /* Bounding rectangle of off-screen */ ° d ONLN dS? <JÃ *
P short depth, /* Desired number of bits per pixel in off-screen */ ° d ONLN d§I <Tï *
E CTabHandle colors, /* Color table to assign to off-screen */ ° d ONLN dÍS <^§ *
H CGrafPtr *retPort, /* Returns a pointer to the new CGrafPort */ ° d ONLN d3] <hï *
E GDHandle *retGDevice) /* Returns a handle to the new GDevice */ ° d ONLN dyg <r A *
{ ° d ONLN d{q <|≥ *
K CGrafPtr newPort; /* Pointer to the new off-screen CGrafPort */ ° d ONLN d«{ <Üü *
G PixMapHandle newPixMap; /* Handle to the new off-screen PixMap */ ° d ONLN dÖ <ê§ *
H GDHandle newDevice; /* Handle to the new off-screen GDevice */ ¡ X¡
} ° d ONLN d™ € ÊÄ *H /* Calculate the number of bytes per row in the off-screen PixMap */ ° d ONLN dÛ Â î *
L bytesPerRow = ((depth * (bounds->right - bounds->left) + 31) >> 5) << 2; ° d ONLN d@ ˘ Ô *+ /* Get the current QuickDraw version */ ° d ONLN dl 5 *
9 (void)Gestalt( gestaltQuickdrawVersion, &qdVersion ); ° d ONLN d¶ "£ *O /* Make sure depth is indexed or depth is direct and 32-Bit QD installed */ ° d ONLN dˆ! ,S *
0 HSetState( (Handle)colors, savedState ); ° d ONLN d⁄ <J *6 /* One Last Look Around The House Before We Go… */ ° d ONLN d
< Ø *
if (error != noErr) ° d ONLN d) <" U *
{ ° d ONLN d/! <,ï *
E /* Some error occurred; dispose of everything we allocated */ ° d ONLN du+ <6 Õ *
if (newPixMap != nil) ° d ONLN dì5 <@ i *
{ ° d ONLN dù? <J6 *
2 DisposCTable( (**newPixMap).pmTable ); ° d ONLN d–I <T, *
0 DisposPtr( (**newPixMap).baseAddr ); ° d ONLN dS <^ i *
} ° d ONLN d ] <h Õ *
if (newDevice != nil) ° d ONLN d)g <r i *
{ ° d ONLN d3q <|c *
; DisposHandle( (Handle)(**newDevice).gdITable ); ° d ONLN do{ <Ü" *
. DisposHandle( (Handle)newDevice ); ° d ONLN dûÖ <ê i *
} ° d ONLN d®è <ö √ *
if (newPort != nil) ° d ONLN dƒô <§ i *
{ ° d ONLN dŒ£ <Æ Ê *
" CloseCPort( newPort ); ° d ONLN dÒ≠ <∏ ˙ *
& DisposPtr( (Ptr)newPort ); ° d ONLN d∑ <¬ i *
} ° d ONLN d"¡ <Ã U *
} ° d ONLN d(À <÷ d *
else ° d ONLN d1’ <‡ U *
{ ° d ONLN d7fl <ͬ *
N /* Everything’s OK; return refs to off-screen CGrafPort and GDevice */ ° d ONLN dÜÈ <Ù √ *
*retPort = newPort; ° d ONLN d¢Û <˛ ‹ *
*retGDevice = newDevice; ° d ONLN d√˝ < U *
} ° d ONLN d… < ë *
return error; ° d ONLN d€ < A *
}
° d ONLN d›' <3; *5CreateOffScreen begins by making sure that the color ° d ONLN d';3˛ )ˇ*table, if there is one, doesn’t get purged ° d ONLN d=3 <? û ([ Zduring the time that ° d ONLN dR3 û?˛ )bGthe off-screen graphics environment is created. Then, a sanity check is ° d ONLN dö? <K ‡ (g Z"done for the given depth, bounds, ° d ONLN dº? ‡K˛ )§<and color table. The depth must be either 1, 2, 4, or 8 bits ° d ONLN d˘K <W n (s Z per pixel, ° d ONLN dK nW˛ )2Ror additionally 16 or 32 bits per pixel if 32-Bit QuickDraw is available. If these ° d ONLN dWW <cç ( ZHconditions aren’t satisfied, then it’s decided that there’s an error in ° d ONLN düWçc˛ (´the parameter list, and ° d ONLN d∑c <oπ (ã ZICreateOffScreen does nothing more. To determine whether 32-Bit QuickDraw ° d ONLN d cπo˛ (ã◊is available or ° d ONLN do <{ c (ó Z not, the
° d ONLN do c{ ì )'_Gestalt
° d ONLN d!o ì{ ñ )0 ° d ONLN d"o ñ{ Ò )routine is used. If
° d ONLN d6o Ò{! )[_Gestalt
° d ONLN d>o!{˛ )00 returns a value that’s equal to or greater than ° d ONLN do{ <á y (£ Z
the constant
° d ONLN d|{ yá Õ )=gestalt32BitQD
° d ONLN dä{ ÕáÇ )T%, then 32-Bit QuickDraw is available ° d ONLN dØ{ÇᲠ)µand depths of 16 and 32 ¡ X¡
° d ONLN d ) X *bits per pixel ° d ONLN d X )c )@7are supported. It’s not necessary to determine whether ,
Courier
° d ONLN d F c )ì ( EÅ_Gestalt
° d ONLN d N ì )⁄ )0 is available or ° d ONLN d _ ) 5Æ ( Q 6Qnot because it’s implemented as glue code in the Macintosh Programmer’s Workshop. ° d ONLN d ± A M L * A check is ° d ONLN d º A L M⁄ )4Pthen done to determine whether the number of bytes in each row of the off-screen ° d ONLN d
M Y _ ( u 6pixel image is ° d ONLN d M _ Y⁄ )GFtoo much for QuickDraw to handle. Color QuickDraw can handle up to and ° d ONLN dc Y e ı ( Å 6+including 16,382 ($3FFE) bytes in each row ° d ONLN dé Y ı e⁄ )›-of any pixel image. If the required number of ° d ONLN dº e qí ( ç 6Mbytes per row exceeds this amount, then CreateOffScreen decides that there’s ° d ONLN d eí q⁄ ( ç∞an error in the ° d ONLN d q }å ( ô 6Kparameter list and does nothing more. The minimum number of bytes in a row ° d ONLN dd qå }⁄ ( ô™that’s enough to ° d ONLN du } âΩ ( • 6[cover the given boundary rectangle at the given pixel depth is calculated with the formula:
° d ONLN d— ï °‘ *J bytesPerRow := ((depth * (bounds.right - bounds.left) + 31) DIV 32) * 4;
° d ONLN d ¨ ∏( *8This formula multiplies the number of pixels across the
° d ONLN dT ¨( ∏L ( ‘FPixMap
° d ONLN dZ ¨L ∏´ )$ by the pixel depth ° d ONLN dn ¨´ ∏⁄ )_
to get the ° d ONLN dy ∏ ƒ x ( ‡ 6number of bits, and ° d ONLN dç ∏ x ƒ⁄ )`Jthen this is divided by eight to get the number of bytes. This division by ° d ONLN dÿ ƒ –ü ( Ï 6Neight looks very strange because the number of bytes per row must be even, so ° d ONLN d& ƒü –⁄ ( ÏΩ this formula ° d ONLN d3 – ‹¶ ( ¯ 6Stakes advantage of integer division and multiplication to make the result come out ° d ONLN dÜ –¶ ‹⁄ ( ¯ƒ
even. This ° d ONLN dë ‹ Ë5 ( 6;particular formula additionally makes sure that the number ° d ONLN dà ‹5 Ë⁄ (S!of bytes per row is a multiple of ° d ONLN dÓ Ë Ù ı ( 6-four. This helps optimize the performance of ° d ONLN d Ë ı Ù⁄ )›,Color QuickDraw operations because it allows ° d ONLN dH Ù ® ( 6OColor QuickDraw to refer to each row beginning on a long word boundary in memor ° d ONLN dó Ù® Æ ( Δy ° d ONLN dò Ù≠ ± ). ° d ONLN dö ° (4 6TThe last sanity check is to make sure that a color table is given as a parameter if ° d ONLN dÓ °⁄ (4ø it’s needed. ° d ONLN d˚ $ ] (@ 6Indexed-color ° d ONLN d ]$⁄ )EPgraphics environments need color tables, so if the given pixel depth is eight or ° d ONLN dZ$ 0 - (L 6less ° d ONLN d_$ -0⁄ )W(which implies an indexed-color graphics environment) and the given color table is NIL, ° d ONLN d∑0 < (X 66then CreateOffScreen decides that there’s an error in ° d ONLN dÌ0<⁄ )˘)the parameter list and does nothing more. ° d ONLN d< H 4 (d 6If the ° d ONLN d < 4H⁄ ) Wgiven pixel depth is 16 or 32 (which implies a direct-color graphics environment), then ° d ONLN dvH T Ú (p 6.CreateOffScreen ignores the given color table. ° d ONLN d•` l *6If all the sanity checks succeed, then the off-screen
° d ONLN d€` lS (à; CGrafPort
° d ONLN d‰`Sl— )6 is allocated using a call ° d ONLN dˇ`—l⁄ )~to
° d ONLN dl x B (î 6_NewPtr
° d ONLN d l Bx ∂ )* , and then it’s initialized ° d ONLN d%l ∂x )tand opened as a
° d ONLN d5lx> )R CGrafPort
° d ONLN d>l>x⁄ )6! by passing the resulting pointer ° d ONLN d`x Ñ $ († 6to
° d ONLN dcx $Ñ ` )
_OpenCPort
° d ONLN dmx `Ñ ë )<
. Because
° d ONLN dwx ëÑ Õ )1
_OpenCPort
° d ONLN dÅx ÕÑ Ò )< makes ° d ONLN dàx ÒÑ )$the new
° d ONLN dêxÑQ )* CGrafPort
° d ONLN dôxQÑ⁄ )6 the current port, the current ° d ONLN d∏Ñ êŒ (¨ 6`port is first saved so that it can be restored as the current port when CreateOffScreen is done. ° d ONLN d ú ® Ç *As mentioned above, ° d ONLN d -ú Ç® ï )jthe
° d ONLN d 1ú ï® Ÿ ) _OpenCPort
° d ONLN d <ú Ÿ®y )D#doesn’t necessarily initialize the
° d ONLN d ë® »¥⁄ )6; to the areas that are needed for any particular off-screen ° d ONLN d Õ¥ ¿ á (‹ 6graphics environment. ° d ONLN d „¥ á¿å )o4So, the given boundary rectangle is assigned to the
° d ONLN d
¥å¿º (‹™portRect
° d ONLN d
¥º¿⁄ )0 field,
° d ONLN d
'¿ Ã H (Ë 6_RectRgn
° d ONLN d
/¿ HÃ ≠ )0 is called to make the
° d ONLN d
F¿ ≠à — )evisRgn
° d ONLN d
L¿ —Ã ¸ )$
equal to ° d ONLN d
V¿ ¸Ã§ )+"the given boundary rectangle, and
° d ONLN d
x¿§Ã⁄ )® _ClipRect
° d ONLN d
ÇÃ ÿ n (Ù 6is called to set the
° d ONLN d
óÃ nÿ ò )VclipRgn
° d ONLN d
ûÃ òÿÉ )*4 so that it’s equal to the given boundary rectangle. ° d ONLN d
”‰ - ( 6The
° d ONLN d
◊‰ - Q )PixMap
° d ONLN d
›‰ Q q )$ in the
° d ONLN d
‰ q ≠ )
portPixMap
° d ONLN d
Ô‰ ≠⁄ )<A field needs to be initialized for off-screen drawing, and that’s ° d ONLN d 1 ¸ ( 64handled by the SetUpPixMap routine that’s described ° d ONLN d e ¸⁄ (<$and defined in “Building the PixMap” ° d ONLN d ä¸ 0 ($ 6later ° d ONLN d ê¸ 0 ô )in this Note. Similarl ° d ONLN d ¶¸ ô ü )iy ° d ONLN d ߸ û Ô ), the off-screen
° d ONLN d ∏¸ Ô )QGDevice
° d ONLN d ø¸⁄ )*( must be created and initialized. That’s ° d ONLN d Ë ` (0 6handled by the ° d ONLN d ˜ `⁄ )HLCreateGDevice routine that’s described and defined in “Building the GDevice” ° d ONLN d D j (< 6later in this Note. ° d ONLN d X, 8 n *Once these things ° d ONLN d j, n8ó )V>are done, CreateOffScreen returns a pointer to the off-screen
° d ONLN d ®,ó8Õ (Tµ CGrafPort
° d ONLN d ±,Õ8⁄ )6 in ° d ONLN d µ8 D ) (` 6the
° d ONLN d π8 )D S )retPort
° d ONLN d ¿8 SD á )* parameter ° d ONLN d À8 áD )4 and a handle to the off-screen
° d ONLN d Í8DE )îGDevice
° d ONLN d Ò8EDh )* in the
° d ONLN d ˘8hD§ )#
retGDevice
° d ONLN d
8§D⁄ )< parameter. ° d ONLN d
D Pº (l 6ZThe way to use these references is described in “Playing With Blocks” later in this Note. ° d ONLN d
j\ h ç *Building the PixMap
° d ONLN d
~t Ä T *
_OpenCPort
° d ONLN d
àt TÄ Ü )<
initializes ° d ONLN d
ït ÜÄ ò )2the
° d ONLN d
ôt òÄ ‘ )
portPixMap
° d ONLN d
£t ‘Ä )< field of the
° d ONLN d
±tÄG )= CGrafPort
° d ONLN d
∫tGÄ⁄ )6! it’s initializing with a copy of ° d ONLN d
‹Ä å , (® 6the
° d ONLN d
‡Ä ,å P )PixMap
° d ONLN d
ÊÄ På ° )$ of the current
° d ONLN d
ˆÄ °å À )QGDevice
° d ONLN d
˝Ä Àå ˜ )*. When ° d ONLN dÄ ˜å⁄ ),-the CreateOffScreen routine described earlier ¡ 4¡˘
° d ONLN d – )Q )* is unknown. So, all the ° d ONLN d 6 Q )ï )Åfields of the
° d ONLN d D ï )π )DPixMap
° d ONLN d J π )˛ )$
that the new
° d ONLN d X ) < 5 r ( Q Z CGrafPort
° d ONLN d a ) r 5f )65 receives must be initialized so that it can be used ° d ONLN d ñ )f 5˛ )Ù for drawing off screen.* What ° d ONLN d ¥ 5 < A Ó ( ] Z&follows is an overview of each of the
° d ONLN d ⁄ 5 Ó A )≤PixMap
° d ONLN d ‡ 5 A^ )$ fields and how ° d ONLN d 5^ A˙ )L"they should be initialized for off ° d ONLN d 5˙ A˛ )ú- ° d ONLN d A < M à ( i Zscreen drawing.
° d ONLN d# Y < e l *baseAddr
° d ONLN d, Y ® e ‹ )l pointer to ° d ONLN d7 Y ‹ e˛ )49the off-screen pixel image. The off-screen pixel image is ° d ONLN dq e ® qá ( ç Δ1allocated as a nonrelocatable block in the heap. ° d ONLN d¢ eá q˛ )flThe size of this block of ° d ONLN dº q ® } Á ( ô Δ
memory is ° d ONLN dΔ q Á }U )?calculated from the
° d ONLN d⁄ qU }Ö )nrowBytes
° d ONLN d‚ qÖ }˛ )0 field, described next, ° d ONLN d˙ } ® â· ( • ΔAmultiplied by the number of rows in the given boundary rectangle.
° d ONLN d< ï < ° l ( Ω ZrowBytes
° d ONLN dE ï ® °j )l)number of bytes in each row of the pixel ° d ONLN dn ïj °˛ )¬ image. This value is calculated ° d ONLN dé ° ® ≠ ˚ ( … Δfrom the formula ° d ONLN dü ° ˚ ≠˛ )S5that’s given in the CreateOffScreen routine. The most ° d ONLN d’ ≠ ® πfi ( ’ ΔDsignificant bit of this field should be set so that Color QuickDraw ° d ONLN d ≠fi π˛ ( ’¸knows ° d ONLN d π ® ≈ Ô ( · Δthat this is a
° d ONLN d. π Ô ≈ )GPixMap
° d ONLN d4 π ≈c )$ rather than a
° d ONLN dC πc ≈á )PBitMap
° d ONLN dI πá ≈˛ )$. The maximum value, ° d ONLN d^ ≈ ® —v ( Ì Δ-ignoring the most significant bit, is 16,382.
° d ONLN då › < È ` ( Zbounds
° d ONLN dì › ® È ‡ )l defines the ° d ONLN dü › ‡ È˛ )88coordinate system and the dimensions of the pixel image. ° d ONLN dÿ È ® ı ÷ ( Δ For most ° d ONLN d· È ÷ ı˛ ).>off-screen drawing, this should be a rectangle that covers the ° d ONLN d ı ®b ( Δ'entire off-screen graphics environment.
° d ONLN dH
< r (5 Z pmVersion
° d ONLN dR
®Ñ )l0set of internally and externally defined flags. ° d ONLN dÇ
Ñ˛ )‹As of 32-Bit QuickDraw ° d ONLN dô ®% Ù (A Δ1.2, only the
° d ONLN dß Ù%0 )L
baseAddr32
° d ONLN d±0%± )< flag is defined externall ° d ONLN dÀ±%∑ )Åy ° d ONLN dÃ∂%ˆ ) . This flag ° d ONLN dÿˆ%˛ )@is ° d ONLN d€% ®1 Ê (M Δ
described in ° d ONLN dË% Ê1˛ )>5“Choosing Your Off-Screen Memory” later in this Note. ° d ONLN d 1 ®=¢ (Y Δ7For most off-screen drawing, this field is set to zero.
° d ONLN d¡Â ®Ò )lformat of the pixels. ° d ONLN d◊Â Ò˛ )c3In indexed-color pixel maps, this field holds zero. ° d ONLN d Ò ®˝ ( ΔIn direct-color pixel ° d ONLN d!Ò˝ó )fmaps, this field holds the
° d ONLN d<Òó˝Õ )â RGBDirect
° d ONLN dEÒÕ˝˛ )6
constant, ° d ONLN dP˝ ® (% Δwhich is equal to 16.
° d ONLN df <! r (= Z pixelSize
° d ONLN dp ®! ¸ )lnumber of bits in ° d ONLN dÇ ¸!˛ )T7every pixel. For indexed-color pixels, this is 1, 2, 4, ° d ONLN d∫! ®-˝ (I ΔNor 8 bits per pixel. For direct-color pixels, this is 16 or 32 bits per pixel.
° d ONLN d 9 <E l (a ZcmpCount
° d ONLN d 9 ®El )l(number of components in every pixel. In ° d ONLN d :9lE˛ )ƒ indexed-color pixel maps, this ° d ONLN d YE ®Q¡ (m Δ:field is set to 1. In direct-color pixel maps, this field ° d ONLN d ìE¡Q˛ (mfl is set to 3. ° d ONLN d †Q ®] ‡ (y Δ
Sometimes ° d ONLN d ™Q ‡]˛ )8;it’s handy to set this field to 4 in 32-bit deep pixel maps ° d ONLN d Ê] ®i Ì (Ö Δ
when they’re ° d ONLN d Û] Ìi˛ )E3being saved in a picture. See the “Color QuickDraw” ° d ONLN d
of 51 (Ï ZM.QD.PrincipiaOffScreen ˇ¢ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier ° d ONLN d ) B *cmpSize
° d ONLN d Ñ )[ )l+number of bits in each color component. In ° d ONLN d 3 [ )⁄ )◊indexed-color pixel maps, ° d ONLN d M ) Ñ 5Y ( Q ¢2this field is set to the same value that’s in the
° d ONLN d )Y 5è )’ pixelSize
° d ONLN d à )è 5⁄ )6 field. In 16-bit ° d ONLN d ö 5 Ñ A ù ( ] ¢deep ° d ONLN d ü 5 ù A⁄ )Fdirect pixel maps, this field is set to 5. In 32-bit deep direct pixel ° d ONLN d Ê A Ñ M ( i ¢ maps, this field is set to 8.
° d ONLN d Y e T ( Å 6
planeBytes
° d ONLN d Y Ñ e\ )l1not currently defined. This field is set to zero.
° d ONLN dA q } B ( ô 6pmTable
° d ONLN dI q Ñ }Z )l,handle to the color table for indexed-color ° d ONLN du qZ }⁄ )÷pixel maps. A method to ° d ONLN dç } Ñ â7 ( • ¢(create a color table is given in “About ° d ONLN dµ }7 â⁄ )≥#That Creation Thing . . .” later in ° d ONLN dŸ â Ñ ï ( ± ¢!this Note. In direct-color pixel ° d ONLN d˙ â ï⁄ )ó'maps, this field contains a handle to a ° d ONLN d" ï Ñ ° Œ ( Ω ¢ dummy color ° d ONLN d. ï Œ °⁄ )J0table, and building one of these is shown in the ° d ONLN d_ ° Ñ ≠( ( … ¢!SetUpPixMap routine in Listing 2.
° d ONLN dÅ π ≈ T ( · 6
pmReserved
° d ONLN då π Ñ ≈\ )l1not currently defined. This field is set to zero. ° d ONLN dæ – ‹ " ( ¯ 6(* ° d ONLN d¿ ” " fl> +
?This part of these routines really bothers me because it feels ° d ONLN dˇ ”> flº ( ˚\ impure to initialize all the
° d ONLN d ‘º fl⁄ )~PixMap
° d ONLN d# fl Î R ( 6 fields when
° d ONLN d/ ‡ R Î Ñ ):
_OpenCPort
° d ONLN d9 fl Ñ Î )2 has initialized them alread ° d ONLN dU fl Î
)Äy ° d ONLN dV fl Î÷ )+, just not in a way that’s any good for off ° d ONLN dÅ fl÷ Î⁄ )Õ- ° d ONLN dÇ Î ˜ ø ( 6%screen drawing. I tried creating the
° d ONLN dß Ï ø ˜ ‚ )ßGDevice
° d ONLN dÆ Î ‚ ˜ ˘ )# and
° d ONLN d≥ Ï ˘ ˜ )PixMap
° d ONLN dπ Î ˜} ) first and then calling
° d ONLN d— Ï} ˜Ø )f
_OpenCPort
° d ONLN d€ ÎØ ˜‘ )2 so that ° d ONLN d‰ Α ˜⁄ )%it ° d ONLN dÁ ˜ U ( 6initializes its
° d ONLN d˜ ¯ U s )=PixMap
° d ONLN d˝ ˜ s ˙ ) for off-screen drawing, but ° d ONLN d ˜ ˙⁄ )á,then you end up with two pixel maps and that ° d ONLN dG 8 (, 6=makes this tougher to explain, or you have to dispose of one ° d ONLN dÑ8b (,VPixMap ° d ONLN däb• )*
which seems ° d ONLN dó•⁄ )C
worse than ° d ONLN d¢ Ö (8 6the method I’m using.) ° d ONLN dπ( 4 *5The SetUpPixMap routine in Listing 2 initializes the
° d ONLN dÓ(44 )¯PixMap
° d ONLN dÙ(44∞ )$ that’s passed to it in the
° d ONLN d(∞4⁄ )|aPixMap
° d ONLN d4 @t (\ 6Hparameter so that it can be used in an off-screen graphics environment. ° d ONLN d`4t@ã (\íThe
° d ONLN d|@ KL ò ) parameters are ° d ONLN då@ òL⁄ )M?the same as the ones passed to the CreateOffScreen routine. The
° d ONLN dÃL X Z (t 6 bytesPerRow
° d ONLN d◊L ZX≠ )BF parameter is the number of bytes in each row of the off-screen pixel ° d ONLN d L≠X⁄ (tÀimage. A ° d ONLN d&X d ˚ (Ä 6/description of SetUpPixMap follows the listing. ° d ONLN dVp | ñ *MPW Pascal Listing 2
° d ONLN dkà ì Å *FUNCTION SetUpPixMap( ° d ONLN dÅí ùÖ *
I depth: Integer; {Desired number of bits/pixel in off-screen} ° d ONLN dÀú ßS *
? bound: Rect; {Bounding rectangle of off-screen} ° d ONLN d ¶ ±b *
B colors: CTabHandle; {Color table to assign to off-screen} ° d ONLN dN∞ ªl *
D bytesPerRow: Integer; {Number of bytes in each row of pixels} ° d ONLN dì∫ ≈q *
E aPixMap: PixMapHandle {Handle to the PixMap being initialized} ° d ONLN dŸƒ œ T *
): OSErr; ° d ONLN dÊÿ „ @ * CONST ° d ONLN dÔ‚ ÌÖ *
I kDefaultRes = $00480000; {Default resolution is 72 DPI; Fixed type} ° d ONLN d9ˆ 6 * VAR ° d ONLN d@ è *
K newColors: CTabHandle; {Color table used for the off-screen PixMap} ° d ONLN då
v *
F offBaseAddr: Ptr; {Pointer to the off-screen pixel image} ° d ONLN d” *
3 error: OSErr; {Returns error code} ° d ONLN d ( 3 1 *BEGIN ° d ONLN d
2 = r *
error := noErr; ° d ONLN d < G | *
newColors := NIL; ° d ONLN d 5F Q ã *
offBaseAddr := NIL; ° d ONLN d MZ e£ *O (* Clone the clut if indexed color; allocate a dummy clut if direct color *) ° d ONLN d ùd o Å *
of 51 (Ï ZM.QD.PrincipiaOffScreen ˇ¬ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ( Ω *! IF newColors <> NIL THEN ° d ONLN d " ' 2 Ã *
$ DisposCTable(newColors); ° d ONLN d G 1 < J *
END; ° d ONLN d R E P ≥ * (* Return the error code *) ° d ONLN d r O Z ï *
SetUpPixMap := error; ° d ONLN d å Y d , *
END;
° d ONLN d ë o { { *MPW C Listing 2
° d ONLN d ° á íô *M#define kDefaultRes 0x00480000 /* Default resolution is 72 DPI; Fixed type */ ° d ONLN d Ô õ ¶ r *OSErr SetUpPixMap( ° d ONLN d • ∞û *
N short depth, /* Desired number of bits/pixel in off-screen */ ° d ONLN dQ Ø ∫l *
D Rect *bounds, /* Bounding rectangle of off-screen */ ° d ONLN dñ π ƒ{ *
G CTabHandle colors, /* Color table to assign to off-screen */ ° d ONLN dfi √ ŒÖ *
I short bytesPerRow, /* Number of bytes per row in the PixMap */ ° d ONLN d( Õ ÿä *
J PixMapHandle aPixMap) /* Handle to the PixMap being initialized */ ° d ONLN ds ◊ ‚ *
{ ° d ONLN du · Ïî *
L CTabHandle newColors; /* Color table used for the off-screen PixMap */ ° d ONLN d¬ Î ˆ{ *
G Ptr offBaseAddr; /* Pointer to the off-screen pixel image */ ° d ONLN d
ı *
4 OSErr error; /* Returns error code */ ° d ONLN d? r * error = noErr; ° d ONLN dR | *
newColors = nil; ° d ONLN dg ( Ü *
offBaseAddr = nil; ° d ONLN d~1 <® *P /* Clone the clut if indexed color; allocate a dummy clut if direct color */ ° d ONLN dœ; F w *
if (depth <= 8) ° d ONLN d„E P 1 *
{ ° d ONLN dÈO Z ü *
newColors = colors; ° d ONLN dY d *
3 error = HandToHand( (Handle *)&newColors ); ° d ONLN d9c n 1 *
newColors = nil; ° d ONLN d¶I <TΩ *M /* If no errors occurred, return a handle to the new off-screen PixMap */ ° d ONLN dÙS <^ Ø *
if (error != noErr) ° d ONLN d ] <h U *
{ ° d ONLN dg <r Õ *
if (newColors != nil) ° d ONLN d0q <| ˙ *
& DisposCTable( newColors ); ° d ONLN dW{ <Ü U *
} ° d ONLN d]è <ö ◊ * /* Return the error code */ ° d ONLN d}ô <§ ë *
return error; ° d ONLN dè£ <Æ A *
}
° d ONLN dëπ <≈( *(SetUpPixMap begins by copying the given ° d ONLN dππ(≈˛ )Ï(color table if an indexed-color graphics ° d ONLN d‚≈ <— (Ì Z,environment is being built, or allocating a ° d ONLN d≈—˛ )‹,dummy color table if a direct-color graphics ° d ONLN d;— <› ˜ (˘ Z&environment is being built. A copy of ° d ONLN da— ˜›˛ )ª5the color table is made because this allows the given ° d ONLN dó› <È · ( Z color table and the off-screen ° d ONLN d∂› ·È˛ )•4graphics environment’s color table to be manipulated ° d ONLN dÎÈ <ı÷ ( ZPindependently without interfering with each other, and this lets the off-screen ° d ONLN d;È÷ı˛ (Ùgraphics ° d ONLN dDı <L ( Z8environment routines manipulate the color table without ° d ONLN d|ıL˛ ( j"needing to worry about whether the ° d ONLN dü <
∂ () ZOcolor table is a 'clut' resource or not. The dummy color table is made so that ° d ONLN dÓ∂
˛ ()‘routines which ° d ONLN d˝
<ß (5 ZKassume that every PixMap has a color table won’t do something catastrophic ° d ONLN dH
߲ (5≈if they find a NIL ° d ONLN d[ <% x (A Z
color table. ° d ONLN dh x%˛ )<MThe off-screen pixel image is then allocated as a nonrelocatable block in the ° d ONLN d∂% <1 ï (M Zapplication’s heap. ° d ONLN d = <I ∞ *Some of the fields of a
° d ONLN d‚= ∞I ‘ )tPixMap
° d ONLN dË= ‘I≈ )$3 have to be initialized differently depending upon ° d ONLN d =≈I˛ )Ò whether the ° d ONLN d 'I <U™ (q ZLindexed-color model or the direct-color model is being used. So, the fields ° d ONLN d sI™U˛ (q»that are the same ° d ONLN d ÖU <a (} Z0regardless of the color model that’s being used ° d ONLN d µUa˛ )fl0are assigned first. Then the desired pixel depth ° d ONLN d Êa <mZ (â Z@is compared to 8. If the depth is less than or equal to 8, then ° d ONLN d
&aZm˛ (âx&the rest of the fields are initialized ° d ONLN d
Mm <y (ï Z,for the indexed-color model. Otherwise, the ° d ONLN d
ymy˛ )“7rest of the fields are initialized for the direct color ° d ONLN d
±y <ÖR (° Z8model. In the case of the direct-color model, the dummy ° d ONLN d
ÈyRÖ˛ (°p%color table is initialized to have no ¡ X¡
° d ONLN d ! ø ) )$ field is set to ° d ONLN d 2 )⁄ )B*three times the component size. This dummy ° d ONLN d ] ) 5 æ ( Q 6'color table is then installed into the
° d ONLN d Ñ ) æ 5 ‚ )¶PixMap
° d ONLN d ä ) ‚ 5 Ê )$. ° d ONLN d å A M ≤ ( i 6 Once SetUpPixMap completes, ° d ONLN d ® A ≤ M ≈ )öthe
° d ONLN d ¨ A ≈ M È )PixMap
° d ONLN d ≤ A È M) )$ of the new
° d ONLN d æ A) M_ )@ CGrafPort
° d ONLN d « A_ M÷ )6 is ready to hold an off ° d ONLN d fl A÷ M⁄ )w- ° d ONLN d ‡ M Y Û ( u 6/screen image. It’s not quite ready to be drawn ° d ONLN d M Û Y⁄ )€-into with Color QuickDraw though. To do that, ° d ONLN d= Y e ^ ( Å 6the off-screen
° d ONLN dL Y ^ e à )FGDevice
° d ONLN dS Y à e ’ )* is still needed; ° d ONLN de Y ’ eù )M+the construction and initialization of the
° d ONLN dê Yù e« )»GDevice
° d ONLN dó Y« e⁄ )* are ° d ONLN dú e q ô ( ç 6 covered in the next section. ° d ONLN dπ } â í *Building the GDevice ° d ONLN dŒ ï ° - *The
° d ONLN d“ ï - ° i )
_OpenCPort
° d ONLN d‹ ï i °G )<3 routine automatically allocates and initializes a
° d ONLN d ïG °k )fiPixMap
° d ONLN d ïk °ó )$
, and the ° d ONLN d ïó °⁄ ), SetUpPixMap ° d ONLN d+ ° ≠ ∞ ( … 6$routine reinitializes that existing
° d ONLN dO ° ∞ ≠ ‘ )òPixMap
° d ONLN dU ° ‘ ≠ € )$.
° d ONLN dW ° € ≠ )
_OpenCPort
° d ONLN da ° ≠£ )<! doesn’t allocate nor initialize ° d ONLN dÇ °£ ≠¨ )åa
° d ONLN dÑ °¨ ≠÷ ) GDevice
° d ONLN dã °÷ ≠⁄ )*, ° d ONLN dç ≠ π & ( ’ 6so ° d ONLN dê ≠ & π⁄ )Vone has to be created from scratch. Pages 21-20 through 21-21 of “The Graphics Devices ° d ONLN dÁ π ≈ Å ( · 6Manager” chapter of ° d ONLN d˚ π Å ≈ Ÿ )iInside Macintosh ° d ONLN d π Ÿ ≈ · )XV ° d ONLN d
π ‡ ≈R )olume VI describe the
° d ONLN d# πR ≈î )r _NewGDevice
° d ONLN d. πî ≈⁄ )B routine. This ° d ONLN d= ≈ — ( Ì 65routine seems as though it’s the ticket to getting a
° d ONLN dr ≈ —A )ˇGDevice
° d ONLN dy ≈A —é )* for off-screen ° d ONLN dâ ≈é —⁄ )Mdrawing, but it ° d ONLN dô — › i ( ˘ 6always allocates ° d ONLN d™ — i › ï )Qthe new
° d ONLN d≤ — ï › ø ),GDevice
° d ONLN dπ — ø ›⁄ )*7 in the system heap. That’s not so good because if your ° d ONLN dÒ › È0 ( 6<program unexpectedly quits or if you just forget to dispose ° d ONLN d- ›0 ÈP (Nof the
° d ONLN d4 ›P Èz ) GDevice
° d ONLN d; ›z È⁄ )* before you quit for ° d ONLN dP È ı G ( 6
real, the
° d ONLN dZ È G ı q )/GDevice
° d ONLN da È q ı ê )* gets ° d ONLN dg È ê ı⁄ ) <orphaned in the system heap. To prevent this from happening,
° d ONLN d§ ı Z ( 6 _NewGDevice
° d ONLN dØ ı Z )B& should be ignored and the off-screen
° d ONLN d’ ı> )∫GDevice
° d ONLN d‹ ı>ã )* should instead ° d ONLN dÏ ıã⁄ )Mbe allocated and ° d ONLN d˝
Æ () 6 initialized from scratch. What ° d ONLN d Æ
∞ )ñ2follows is a description of how each field of the
° d ONLN dN∞
⁄ ()ŒGDevice
° d ONLN dV
¶ (5 6 structure should be initialized.
° d ONLN dw% 1 H *gdRefNum
° d ONLN dÄ% Ñ1 ¥ )l
reference ° d ONLN dä% ¥1⁄ )08number of video driver. Off-screen graphics environments ° d ONLN d√1 Ñ= ø (Y ¢ don’t need ° d ONLN dŒ1 ø=⁄ );5to have video drivers because there’s no video device ° d ONLN d= ÑIf (e ¢3associated with them, so this field is set to zero.
° d ONLN d8U a 0 (} 6gdID
° d ONLN d=U Ña )lused to identify specific
° d ONLN dWUa= )èGDevice
° d ONLN d^U=a† )* structures from ° d ONLN doU†a⁄ )c color-search ° d ONLN d|a Ñmv (â ¢0procedures. This isn’t necessary for off-screen ° d ONLN d¨avm⁄ )Údrawing, so this is ° d ONLN d¿m Ñy  (ï ¢normally set to zero.
° d ONLN d÷Ö ë < (≠ 6gdType
° d ONLN d›Ö Ñë ™ )ltype of
° d ONLN dÂÖ ™ë ‘ )&GDevice
° d ONLN dÏÖ ‘ë )*
. This field ° d ONLN d˘Öëz ):is set to the constant
° d ONLN dÖzë™ )lclutType
° d ONLN dÖ™ë⁄ )0
(equal to ° d ONLN d#ë Ñù (π ¢zero) for an indexed-color ° d ONLN d>ëù⁄ )í#environment and set to the constant
° d ONLN d£µ Ñ¡# )l%handle to the inverse table. Initiall ° d ONLN d»µ#¡) )üy ° d ONLN d…µ(¡¡ )&, this field is set to an arbitrarily ° d ONLN dÔµ¡¡⁄ )ôsmall ° d ONLN dı¡ ÑÕ › (È ¢handle. Later, the
° d ONLN d¡ ›Õ )Y _MakeITable
° d ONLN d¡ ÕT )B routine is ° d ONLN d ¡TÕ⁄ )5 used to resize and initialize ° d ONLN d=Õ ÑŸ! (ı ¢$this handle to a real inverse table.
° d ONLN dbÂ Ò N (
6 gdResPref
° d ONLN dl ÑÒ )l inverse-table resolution. When
° d ONLN dãÂÒ] )ó _MakeITable
° d ONLN dñÂ]Ò⁄ )B is called by QuickDraw, ° d ONLN dØÒ Ñ˝ æ ( ¢
the value of ° d ONLN dºÒ æ˝⁄ ):>this field is used as the inverse-table resolution. Almost all ° d ONLN d˚˝ Ñ B (% ¢'inverse tables have a resolution of 4. ° d ONLN d "˝B ⁄ )æThere are some cases when a ° d ONLN d > Ñ@ (1 ¢)inverse-table resolution of 5 is useful, ° d ONLN d g @⁄ )º particularly when the arithmetic ° d ONLN d à Ñ! ˜ (= ¢transfer modes are used ° d ONLN d † ˜! )swith
° d ONLN d •!F ) _CopyBits
° d ONLN d ÆF!⁄ )6 . See “The GDevice” earlier in ° d ONLN d Õ! Ñ- ≥ (I ¢
this Note.
° d ONLN d ÿ9 E ` (a 6 gdSearchProc
° d ONLN d Â9 ÑE À )lpointer to the ° d ONLN d Ù9 ÀE⁄ )G6color-search procedure. If a color-search procedure is ° d ONLN d
+E ÑQb (m ¢3needed, this field can be set later by calling the
° d ONLN d
^EbQû )fi
_AddSearch
° d ONLN d
hEûQ⁄ )<
routine (see ° d ONLN d
vQ Ñ] (y ¢ the “Color Manager” chapter ° d ONLN d
íQ] )äof ° d ONLN d
ïQ ]r )Inside Macintosh ° d ONLN d
¶Qr]z )VV ° d ONLN d
ßQy]ö )olume ° d ONLN d
≠Qö]¢ )!V ° d ONLN d
ÆQ°]⁄ ) , pages 145 ° d ONLN d
∫] Ñi Ë (Ö ¢through 147). Usuall ° d ONLN d
Œ] Ëi Ó )dy ° d ONLN d
œ] Ìi∏ )1, this field is just set to NIL and left at that. ¡ 4¡˘
procedure ° d ONLN d V ) ⁄ 5Œ )26is needed, this field can be set later by calling the
° d ONLN d å )Œ 5˛ )Ù_AddComp
° d ONLN d ï 5 ® AL ( ] Δ!routine (see the “Color Manager” ° d ONLN d ∂ 5L AÇ )§ chapter of ° d ONLN d ¡ 5Ç A⁄ )6Inside Macintosh ° d ONLN d “ 5⁄ A‚ )XV ° d ONLN d ” 5· A˛ )olume ° d ONLN d Ÿ A ® M ∞ ( i ΔV ° d ONLN d ⁄ A Ø M ∂ ), ° d ONLN d ‹ A ∂ MQ ) pages 145 through 147). Usuall ° d ONLN d ˙ AQ MW )õy ° d ONLN d ˚ AV M˛ )&, this field is set to NIL and left at ° d ONLN d" M ® Y Ω ( u Δthat.
° d ONLN d( e < q f ( ç ZgdFlags
° d ONLN d0 e ® q )lflags indicating certain ° d ONLN dI e qS )mstates of the
° d ONLN dW eS q} )>GDevice
° d ONLN d^ e} q˛ )* . This field should initially ° d ONLN d| q ® }# ( ô Δ be set to zeroes. After the
° d ONLN dò q# }M ){GDevice
° d ONLN dü qM }≥ )* has been built, these ° d ONLN d∂ q≥ }˛ )fflags can be set ° d ONLN d« } ® â › ( • Δ with the
° d ONLN d– } › â7 )5_SetDeviceAttrs
° d ONLN dfl }7 âj )Z routine ° d ONLN dË }j Ⲡ)3(see the “Graphics Devices ° d ONLN d â ® ï ( ± ΔManager” chapter of ° d ONLN d â ï_ )cInside Macintosh ° d ONLN d( â_ ïg )TV ° d ONLN d) âf ïÜ )olume ° d ONLN d/ âÜ ï˙ ) VI, pages 21-10 and 21 ° d ONLN dE â˙ ï˛ )t- ° d ONLN dF ï ® ° º ( Ω Δ22).
° d ONLN dK ≠ < π ` ( ’ ZgdPMap
° d ONLN dR ≠ ® π fi )l handle to a
° d ONLN d^ ≠ fi π )6PixMap
° d ONLN dd ≠ πB )$. A handle to ° d ONLN dr ≠B πT )@the
° d ONLN dv ≠T πx )PixMap
° d ONLN d| ≠x πú )$ of the
° d ONLN dÑ ≠ú π“ )$ CGrafPort
° d ONLN dç ≠“ π˛ )6 that was ° d ONLN dó π ® ≈K ( · Δ'created earlier is put into this field.
° d ONLN dø — < › l ( ˘ ZgdRefCon
° d ONLN d» — ® ›
)lmiscellaneous data.
° d ONLN d‹ —
›I )e
_CalcCMask
° d ONLN dÊ —I ›f )< and
° d ONLN dÎ —f ›¢ )
_SeedCFill
° d ONLN dı —¢ ›˛ )< use this field as ° d ONLN d › ® Èm ( Δ$described on pages 71 through 72 of ° d ONLN d, ›m Èê )≈Inside ° d ONLN d3 ›ê È» )#
Macintosh ° d ONLN d= ›» È– )8V ° d ONLN d> ›œ ÈÛ )olume ° d ONLN dD ›Û È˚ )$V ° d ONLN dE ›˙ È˛ ). ° d ONLN dG È ® ı Δ ( ΔInitiall ° d ONLN dO È Δ ı à ) y ° d ONLN dP È À ı= ) , this field is set to zero.
° d ONLN dm <
l () ZgdNextGD
° d ONLN dv ®
Û )lhandle to next
° d ONLN dÖ Û
)KGDevice
° d ONLN då
C )* in the
° d ONLN dîC
m )&GDevice
° d ONLN dõm
Δ )* list. The system ° d ONLN d≠Δ
˛ )Y maintains a ° d ONLN dπ
® » (5 Δlinked ° d ONLN d¿
» Ë ) list of
° d ONLN d»
Ë ) GDevice
° d ONLN dœ
§ )* records in which there’s one
° d ONLN dÌ
§Œ )íGDevice
° d ONLN dÙ
Œ˛ )*
for every ° d ONLN dˇ ®% ˛ (A Δscreen, and the ° d ONLN d ˛%‘ )V)links are kept in this field. Off-screen
° d ONLN d8‘%˛ )÷GDevice
° d ONLN d@% ®1± (M Δ=structures should never be put into this list, so this field ° d ONLN d}%±1˛ (Mœshould be set to ° d ONLN dé1 ®= ¿ (Y ΔNIL.
° d ONLN dìI <U ` (q ZgdRect
° d ONLN döI ®U Ë )l
rectangle of
° d ONLN dßI ËU )@GDevice
° d ONLN dÆIU‘ )*(. Strictly speaking, this field is used ° d ONLN d÷I‘U˛ )¬only for ° d ONLN dflU ®a_ (} Δ&screens, but it should be the same as ° d ONLN dU_ar )∑the
° d ONLN d Urañ )bounds
° d ONLN dUña˙ )$ rectangle of the off ° d ONLN d$U˙a˛ )d- ° d ONLN d%a ®m … (â Δscreen
° d ONLN d,a …m Ì )!PixMap
° d ONLN d2a Ìm Ò )$.
° d ONLN d4y <Ö ` (° ZgdMode
° d ONLN d;y ®ÖE )l"current video mode. This field is ° d ONLN d]yEÖ˛ )ù&used by video drivers to keep track of ° d ONLN dÑÖ ®ë ∫ (≠ Δthe ° d ONLN dàÖ ∫ë‘ )9current mode that the video device is in. For off-screen
° d ONLN d¡Ö‘ë˛ (≠ÚGDevice
° d ONLN d…ë ®ùd (π Δ+structures, this field should be set to -1.
° d ONLN dVµ¡Ó )*0 structures, these fields should be set to zero.
° d ONLN dáÕ <Ÿ x (ı Z
gdReserved
° d ONLN díÕ ®ŸÄ )l1not currently defined. This field is set to zero. ° d ONLN dƒÂ <Ò S (
ZThe ° d ONLN d»Â SÒ‘ )KCreateGDevice routine shown below in Listing 3 allocates and initializes a
° d ONLN dÂ‘Ò˛ (
ÚGDevice
° d ONLN dÒ <˝ ( Z/structure. It takes the initialized off-screen
° d ONLN dJÒ ˝/ )œPixMap
° d ONLN dPÒ/˝@ )$ in ° d ONLN dTÒ@˝S )the
° d ONLN dXÒS˝è )
basePixMap
° d ONLN dbÒè˝˛ )< parameter and returns ° d ONLN dy˝ < M (% Zthe ° d ONLN d}˝ M ~ ) initialized
° d ONLN dâ˝ ~ ® )1GDevice
° d ONLN dê˝ ® À )* in the
° d ONLN dò˝ À )#
retGDevice
° d ONLN d¢˝ ˛ )<2 parameter. If any error occurs, any memory that’s ° d ONLN d’ <ö (1 ZNallocated is disposed of and the result code is returned as a function result. ° d ONLN d$! <- ∫ *MPW Pascal Listing 3
° d ONLN d99 <D Ø *FUNCTION CreateGDevice( ° d ONLN dQC <NÆ *
J basePixMap: PixMapHandle; {Handle to the PixMap to base GDevice on} ° d ONLN dúM <Xö *
F VAR retGDevice: GDHandle {Returns a handle to the new GDevice} ° d ONLN d„W <b x *
): OSErr; ° d ONLN dk <v d * CONST ° d ONLN d˘u <Ä" *
of 51 (Ï ZM.QD.PrincipiaOffScreen ˇû ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d (û *N (**newDevice).gdRect = deviceRect; /* Use PixMap dimensions */ ° d ONLN d O ' 2{ *
G (**newDevice).gdMode = -1; /* For nonscreens */ ° d ONLN d ó 1 <û *
N (**newDevice).gdCCBytes = 0; /* Only used for screens */ ° d ONLN d Ê ; Fû *
N (**newDevice).gdCCDepth = 0; /* Only used for screens */ ° d ONLN d5 E Pû *
N (**newDevice).gdCCXData = 0; /* Only used for screens */ ° d ONLN dÑ O Zû *
N (**newDevice).gdCCXMask = 0; /* Only used for screens */ ° d ONLN d” Y dÖ *
I (**newDevice).gdReserved = 0; /* Currently unused */ ° d ONLN d m xl *D /* Set color-device bit if PixMap isn’t black & white */ ° d ONLN db w Ç ˘ *
- if ((**basePixMap).pixelSize > 1) ° d ONLN dê Å å] *
A SetDeviceAttribute( newDevice, gdDevType, true ); ° d ONLN d“ ï †ä *J /* Set bit to indicate that the GDevice has no video driver */ ° d ONLN d ü ™D *
< SetDeviceAttribute( newDevice, noDriver, true ); ° d ONLN dZ ≥ æ ˛ *. /* Initialize the inverse table */ ° d ONLN dâ Ω » ˛ *
. if ((**basePixMap).pixelSize <= 8) ° d ONLN d∏ « “ Y *
{ ° d ONLN dΔ — ‹è *
K MakeITable( (**basePixMap).pmTable, (**newDevice).gdITable, ° d ONLN d € Ê *
2 (**newDevice).gdResPref ); ° d ONLN dE Â ¬ *
" error = QDError(); ° d ONLN dh Ô ˙ Y *
} ° d ONLN dv ˘ E *
} ° d ONLN dÄ T *
else ° d ONLN dç
≥ *
error = MemError(); ° d ONLN d≠ " 1 *
} ° d ONLN d≥! , @ *
else ° d ONLN dº+ 6 ü *
error = MemError(); ° d ONLN dÿ? J Â *) /* Handle any errors along the way */ ° d ONLN dI T ã *
. DisposHandle( (Handle)newDevice ); ° d ONLN dºÖ ê 1 *
} ° d ONLN d¬è ö @ *
else ° d ONLN dÀô § ∏ *
*retGDevice = newDevice; ° d ONLN dÏ≠ ∏ Ù *, /* Return a handle to the new GDevice */ ° d ONLN d∑ ¬ m *
return error; ° d ONLN d+¡ Ã *
}
° d ONLN d-◊ „ ô *CreateGDevice begins by ° d ONLN dE◊ ô„ ‡ )Åallocating the
° d ONLN dT◊ ‡„
)GGDevice
° d ONLN d[◊
„⁄ )*' structure and an embryonic form of the ° d ONLN dÉ„ Ô ¥ ( 6#inverse table in the current heap. ° d ONLN d¶„ ¥Ô⁄ )ú?The inverse table is allocated as two zero bytes for now; it’ll ° d ONLN dÊÔ ˚= ( 6?be resized and initialized to be a real inverse table later in ° d ONLN d%Ô=˚⁄ ([ this routine. Then, each of the
° d ONLN dE˚ B (# 6GDevice
° d ONLN dL˚ B )*- fields are initialized as described earlier. ° d ONLN dz . (; 60After all the fields have been initialized, the
° d ONLN d™. X (;LgdFlags
° d ONLN d±X d )*
° d ONLN d≤d ⁄ ) field is set through
° d ONLN d« + ä (G 6_SetDeviceAttribute
° d ONLN d⁄ ä+ )r . If the desired pixel depth is ° d ONLN d˙ +à )ägreater than 1, then the
° d ONLN d à+æ )t gdDevType
° d ONLN d æ+⁄ )6 bit is ° d ONLN d$+ 7 ï (S 6 set. This indicates that the
° d ONLN dA+ ï7 ø )}GDevice
° d ONLN dH+ ø7 Ê )*
is for a ° d ONLN dR+ Ê7⁄ )'2color graphics environment. This bit should be set ° d ONLN dÖ7 CQ (_ 6Feven if a gray-scale color table is used for this off-screen graphics ° d ONLN dÀ7QC™ (_oenvironment. The
° d ONLN d‹7™C⁄ )YnoDriver
° d ONLN dÂC O ⁄ (k 6)bit is set because this is an off-screen
° d ONLN d C ⁄O )¬GDevice
° d ONLN d COT )* and so there’s ° d ONLN d %CTO⁄ )Pno associated video device ° d ONLN d @O [ 8 (w 6driver. ° d ONLN d Hg s 3 *Finall ° d ONLN d Ng 3s 9 )y ° d ONLN d Og 8sC )>, the inverse table is resized and initialized by calling the
° d ONLN d çgCsÖ (èa _MakeITable
° d ONLN d ògÖsª )B routine. A ° d ONLN d §gªs⁄ )6handle ° d ONLN d ´s « (õ 6\to the two-byte embryonic inverse table that was created earlier in CreateGDevice is passed ° d ONLN d
s«⁄ (õÂas a ° d ONLN d
ãÿ (ß 6cparameter, as is a handle to the off-screen color table and the preferred inverse-table resolution. ¡ 4¡˘
All Fall Down ° d ONLN d 5 < A≈ *RNow that we have a way to create an off-screen graphics environment, there has to ° d ONLN d ` 5≈ A˛ ( ]„ be a way to ° d ONLN d l A < M e ( i Zget rid ° d ONLN d t A e M˛ ))Iof it too. The DisposeOffScreen routine shown in Listing 4 does this. The ° d ONLN d æ M < YÁ ( u ZVCreateOffScreen routine returns an off-screen graphics environment that’s represented ° d ONLN d MÁ Y˛ ( uby a ,
Courier
° d ONLN d Y < e r ( Å Z CGrafPort
° d ONLN d" Y r e u )6 ° d ONLN d# Y u e ä )and
° d ONLN d' Y ä e ¥ )GDevice
° d ONLN d. Y ¥ e≥ )*4. The DisposeOffScreen routine takes the off-screen
° d ONLN db Y≥ eÈ )ˇ CGrafPort
° d ONLN dk YÈ e˛ )6 and
° d ONLN dp e < q f ( ç ZGDevice
° d ONLN dw e f q } )* and ° d ONLN d| e } q» )Edeallocates all the memory that’s associated with them including the
° d ONLN d¡ e» q˛ ( çÊ CGrafPort
° d ONLN dÀ q < } ◊ ( ô Z"and its dependent structures, the
° d ONLN dÌ q ◊ } )õGDevice
° d ONLN dÙ q } )*, the
° d ONLN d˙ q }= )PixMap
° d ONLN d q= }Ò )$), the color table, and the inverse table. ° d ONLN d* â < ï ∫ ( ± ZMPW Pascal Listing 4
° d ONLN d? ° < ¨ √ *PROCEDURE DisposeOffScreen( ° d ONLN d[ ´ < ∂≥ *
K doomedPort: CGrafPtr; {Pointer to the CGrafPort we’re getting rid of} ° d ONLN dß µ < ¿§ *
H doomedGDevice: GDHandle {Handle to the GDevice we’re getting rid of} ° d ONLN d ø < U *
); ° d ONLN dˆ ” < fi Z * VAR ° d ONLN d˝ › < Ë^ *
: currPort: CGrafPtr; {Pointer to the current port} ° d ONLN d8 Á < Úh *
< currGDevice: GDHandle; {Handle to the current GDevice} ° d ONLN du ˚ < U *BEGIN ° d ONLN d{ <ö *
F (* Check to see whether the doomed CGrafPort is the current port *) ° d ONLN d¬ < “ *
GetPort(GrafPtr(currPort)); ° d ONLN d· <$ ‹ *
IF currPort = doomedPort THEN ° d ONLN d# <. s *
BEGIN ° d ONLN d- <8Ü *
B (* It is; set current port to Window Manager CGrafPort *) ° d ONLN dQ7 <B ‹ *
GetCWMgrPort(currPort); ° d ONLN drA <L *
$ SetPort(GrafPtr(currPort)); ° d ONLN dóK <V n *
END; ° d ONLN d¢_ <jü *G (* Check to see whether the doomed GDevice is the current GDevice *) ° d ONLN dÍi <t Õ *
currGDevice := GetGDevice; ° d ONLN ds <~ ˙ *
& IF currGDevice = doomedGDevice THEN ° d ONLN d/} <àã *
C (* It is; set current GDevice to the main screen’s GDevice *) ° d ONLN dsá <í ‹ *
SetGDevice(GetMainDevice); ° d ONLN dîõ <¶ “ * (* Throw everything away *) ° d ONLN d≥• <∞ · *
I GDHandle doomedGDevice) /* Handle to the GDevice to be disposed of */ ° d ONLN dç7 <B A *
{ ° d ONLN dèA <Lc *
; CGrafPtr currPort; /* Pointer to the current port */ ° d ONLN dÀK <Vm *
= GDHandle currGDevice; /* Handle to the current GDevice */ ° d ONLN d _ <jü *G /* Check to see whether the doomed CGrafPort is the current port */ ° d ONLN dQi <t *
° d ONLN d‹ Ò ˝a *>One mildly tricky aspect of this is that we shouldn’t dispose ° d ONLN d Òa ˝⁄ (of the current graphics ° d ONLN d2 ˝ A (% 6Aenvironment. To prevent this, the current port is retrieved by a ° d ONLN ds ˝A b (%_call to
° d ONLN dè!b-⁄ )B. If it returns a handle to ° d ONLN d´- 9 D (U 6 the same
° d ONLN d¥- D9 n ),GDevice
° d ONLN dª- n9 Ö )* that ° d ONLN d¡- Ö9⁄ )GDisposeOffScreen is disposing, then the current port is set to the main ° d ONLN d 9 E B (a 6 screen’s
° d ONLN d9 BE l )*GDevice
° d ONLN d9 lE „ )*. Again, that’s an arbitrar ° d ONLN d49 „E È )wy ° d ONLN d59 ËE4 ), neutral choice. ° d ONLN dGQ ] o (y 6The inverse table,
° d ONLN dZQ o] ô )WGDevice
° d ONLN daQ ô] › )*, pixel image, ° d ONLN dpQ ›]⁄ )D4and color table are disposed of. Before disposing of ° d ONLN d•] iê (Ö 6Othe color table, a check is first made to see whether it’s NIL. That’s because ° d ONLN dÙ]êi⁄ (ÖÆit’s reasonable, ° d ONLN di u ù (ë 6though not normal, for the
° d ONLN dÊÅ Ïçx )$ . Once this is done, all the ° d ONLN dÅxç⁄ )åstructures that were ° d ONLN dç ô (µ 63created by calling CreateOffScreen are deallocated.
° d ONLN dL± ¿ † *'Playing With Blocks
° d ONLN d`à ÿ h *Now that these ° d ONLN doà hÿ⁄ )PHfour routines with two entry points can create and dispose of off-screen ° d ONLN d∏ÿ ‰ œ ( 6$graphics environments, how are they ° d ONLN d‹ÿ œ‰⁄ )∑5used? There are several phases to using an off-screen ° d ONLN d‰ ˛ ( 60graphics environment: creating it, drawing into ° d ONLN dB‰ ˛⁄ )Ê-it, switching between it and other off-screen ° d ONLN dp ¸¿ ( 6Rand on-screen graphics environments, copying images to and from it, and disposing ° d ONLN d¬¿¸⁄ (fiof it. ° d ONLN d…¸ ò ($ 6Listing 5 shows a routine ° d ONLN d„¸ ò⁄ )Ä@called ExerciseOffScreen which is a very basic example of all of ° d ONLN d $ W (0 6
these phases. ° d ONLN d 2 , ñ *MPW Pascal Listing 5
° d ONLN d G8 C § * PROCEDURE ExerciseOffScreen; ° d ONLN d dL W @ * CONST ° d ONLN d mV aô *
M kOffDepth = 8; {Number of bits per pixel in off-screen environment} ° d ONLN d ª` k5 *
9 rGrayClut = 1600; {Resource ID of gray-scale clut} ° d ONLN d ıj u5 *
9 rColorClut = 1601; {Resource ID of full-color clut} ¡ 4¡˘
J CGrafPtr grayPort; /* Graphics environment for gray off screen */ ° d ONLN dqΩ »{ *
G GDHandle grayDevice; /* Color environment for gray off screen */ ° d ONLN dπ« “è *
K CGrafPtr colorPort; /* Graphics environment for color off screen */ ° d ONLN d— ‹Ä *
H GDHandle colorDevice; /* Color environment for color off screen */ ° d ONLN dN€ Êè *
K GrafPtr savedPort; /* Pointer to the saved graphics environment */ ° d ONLN döÂ { *
G GDHandle savedDevice; /* Handle to the saved color environment */ ° d ONLN d‚Ô ˙l *
D CTabHandle offColors; /* Colors for off-screen environments */ ° d ONLN d'˘ v *
F Rect offRect; /* Rectangle of off-screen environments */ ° d ONLN dn S *
? Rect circleRect; /* Rectangles for circle-drawing */ ° d ONLN dÆ
*
1 short count; /* Generic counter */ ° d ONLN d‡ "g *
C RGBColor aColor; /* Color used for drawing off screen */ ° d ONLN d $! ,{ *
G OSErr error; /* Error return from off-screen creation */ ° d ONLN d l5 @{ *G /* Set up the rectangle for the off-screen graphics environments */ ° d ONLN d ¥? J ‡ *
( SetRect( &offRect, 0, 0, 256, 256 ); ° d ONLN d ›S ^ä *J /* Get the color table for the gray off-screen graphics environment */ ° d ONLN d
(] h € *
' offColors = GetCTable( rGrayClut ); ° d ONLN d
Pq |5 *9 /* Create the gray off-screen graphics environment */ ° d ONLN d
ä{ ÜD *
< error = CreateOffScreen( &offRect, kOffDepth, offColors, ° d ONLN d
of 51 (Ï ZM.QD.PrincipiaOffScreen ˇí ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d (] *A /* Dispose of the off-screen graphics environments */ ° d ONLN d B ' 2! *
5 DisposeOffScreen( grayPort, grayDevice ); ° d ONLN d x 1 <+ *
7 DisposeOffScreen( colorPort, colorDevice ); ° d ONLN d ∞ ; F E *
} ° d ONLN d ∫ E P 1 *
} ° d ONLN d ¿ O Z *
}
° d ONLN d ¬ e q_ *?Two off-screen graphics environments are created in the same wa ° d ONLN d e_ qe ( ç}y ° d ONLN d ed q» ). A rectangle that’s ° d ONLN d e» q⁄ )d256 ° d ONLN d q } ( ô 65pixels wide by 256 pixels high and with its top-left ° d ONLN dP q }⁄ ( ô=&coordinate at (0, 0) is created in the
° d ONLN dw } â B ( • 6offRect
° d ONLN d~ } B â ¶ )* local variable. 'clut' ° d ONLN dñ } ¶ â⁄ )d@resources are loaded from the application’s resource fork to use ° d ONLN d◊ â ï 6 ( ± 6as the ° d ONLN dfi â 6 ï⁄ ) Zcolor tables of the two off-screen graphics environments; a gray-scale 'clut' in the first ° d ONLN d9 ï ° 1 ( Ω 6case ° d ONLN d> ï 1 °⁄ )Tand a full-color 'clut' in the second case. Then, CreateOffScreen is called with the ° d ONLN dì ° ≠t ( … 6Mrectangle, color table, and a hard-coded pixel depth of eight bits per pixel. ° d ONLN d· π ≈ ò *If CreateOffScreen returns
° d ONLN d¸ π ò ≈ ∂ )ÄnoErr
° d ONLN d π ∂ ≈t ) * in both cases, then the current graphics ° d ONLN d+ πt ≈⁄ )æenvironment is saved ° d ONLN d@ ≈ —Q ( Ì 6@so that it can be restored later. Graphics environments consist ° d ONLN dÄ ≈Q —⁄ ( Ìoof the current port and the ° d ONLN dú — › = ( ˘ 6current
° d ONLN d§ — = › g )%GDevice
° d ONLN d´ — g › ™ )*. The current
° d ONLN dπ — ™ › ⁄ )CGrafPort
° d ONLN d¡ — ⁄ › Ï )0 or
° d ONLN d≈ — Ï ›" ) CGrafPort
° d ONLN dŒ —" ›j )6 is saved with
° d ONLN d› —j ›ö )H_GetPort
° d ONLN d —ö ›¢ )0. ° d ONLN dÁ —¢ ›⁄ ) The current
° d ONLN dÛ › È B ( 6GDevice
° d ONLN d˙ › B È Ü )* is saved with
° d ONLN d › Ü È » )D _GetGDevice
° d ONLN d › » È Ã )B. ° d ONLN d ı Œ ( 6ZThe gray-scale off-screen graphics environment is set as the current graphics environment ° d ONLN dp ıŒ⁄ ( Ïby ° d ONLN ds
; () 6calling
° d ONLN d{ ;
k )#_SetPort
° d ONLN dÉ k
ó )0
with its
° d ONLN dç ó
Õ ), CGrafPort
° d ONLN dñ Õ
)6
and calling
° d ONLN d£
K )< _SetGDevice
° d ONLN dÆK
h )B with ° d ONLN d¥h
x ) its
° d ONLN d∏x
¢ )GDevice
° d ONLN dø¢
⁄ )* . A vertical ° d ONLN dÃ
2 (5 6;gray ramp is drawn into this graphics environment with the ° d ONLN d
2⁄ (5P"usual set of QuickDraw calls. This ° d ONLN d* %≤ (A 6Ographics environment’s pixel image is then copied to the full-color off-screen ° d ONLN dy≤%⁄ (A–graphics ° d ONLN dÇ% 1Å (M 6Kenvironment with dithering and colorization with green (dithering requires ° d ONLN dÕ%Å1⁄ (Mü32-Bit QuickDraw ° d ONLN dfi1 = - (Y 6and ° d ONLN d‚1 -=⁄ )Xconsistent colorization requires system software version 7.0; both of these features are ° d ONLN d;= I (e 66described in Konstantin Othmer’s article “QuickDraw’s ° d ONLN dq= I⁄ (e>$CopyBits Procedure: Better Than Ever ° d ONLN dñI U % (q 6in ° d ONLN dôI %U ≠ )
System 7.0” in Issue 6 of ° d ONLN d≥I ≠U “ )àdevelop ° d ONLN d∫I “U⁄ )%6). Before this copy happens, the full-color off-screen ° d ONLN dÒU a ± (} 6 graphics environment must be ° d ONLN dU ±aé )ô+set as the current one. Once this is done,
° d ONLN d :µ Z¡ ¨ )B. The off-screen ° d ONLN d Kµ ¨¡⁄ )R;image is then copied to the saved graphics environment with
° d ONLN d á¡ Õ N (È 6 _CopyBits
° d ONLN d ê¡ NÕ R )6. ° d ONLN d íŸ Â ± ( 6 Finally, the two off-screen ° d ONLN d ÆŸ ±Â⁄ )ô4graphics environments are disposed of by calling the ° d ONLN d „ ҫ (
6]DisposeOffScreen routine that’s defined in the section “All Fall Down” earlier in this Note.
° d ONLN d
A £ *'Put That Checkbook ° d ONLN d
T £ Æ )ãA ° d ONLN d
U ≠ Õ )
way!
° d ONLN d
Z$ 0x (L 6>The previous section covered the basics of creating and using ° d ONLN d
ò$x0⁄ (Lñoff-screen graphics ° d ONLN d
¨0 < Ó (X 6)environments. This is good enough for man ° d ONLN d
’0 Ó< Ù )÷y ° d ONLN d
÷0 Û<ô )#, if not most, needs of off-screen ° d ONLN d
˘0ô<⁄ )¶ drawing. But ° d ONLN d < H ˆ (d 61there are variations to creating and maintaining ° d ONLN d 7< ˆH⁄ )fi/an off-screen graphics environment for specific ° d ONLN d gH TC (p 6=cases. This section discusses a few of the more common cases. ° d ONLN d •` l À * About That Creation Thing . . . ° d ONLN d ≈x Ñà *VThe CreateOffScreen routine, defined in Listing 1, takes three pieces of information: ° d ONLN d xÃÑ⁄ (†Íthe ° d ONLN d Ñ êÄ (¨ 6Nboundary rectangle, the desired pixel depth, and the desired color table. But ° d ONLN d mÑÄê⁄ (¨ûthere’s much more ¡ 4¡˘
(÷ 628 )
of 51 )‚2QD 13 - Principia Off-Screen Graphics Environments +nM.QD.PrincipiaOffScreen ˇ v ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ï
March 1992 / X /
° d ONLN d < )◊ ( E ZRto these pieces than ExerciseOffScreen shows. This section describes these pieces ° d ONLN d R ◊ )˛ ( Eıin more ° d ONLN d Z ) < 5 Y ( Q Zdetail. ° d ONLN d b A < M ı *'The first parameter to CreateOffScreen ° d ONLN d â A ı M˛ )π7is a rectangle which determines the size and coordinate ° d ONLN d ¡ M < Y= ( u Z5system of the off-screen graphics environment. Usuall ° d ONLN d ˆ M= YC ( u[y ° d ONLN d ˜ MB Y† ), the top-left corner ° d ONLN d
M† Y˛ )^of the rectangle has ° d ONLN d" Y < e Ÿ ( Å Z#the coordinate (0, 0) because it’s ° d ONLN dE Y Ÿ e˛ )ù=usually easiest to draw everything using coordinates that can ° d ONLN dÉ e < q‚ ( ç Z^also be thought of as the horizontal and vertical distance in pixels from the top-left corner ° d ONLN d· e‚ q˛ ( ç of the ° d ONLN dË q < }ò ( ô ZFgraphics environment. But in some cases, it’s more convenient to have ° d ONLN d. qò }˛ ( ô∂the (0, 0) coordinate ° d ONLN dD } < âà ( • ZRsomewhere else, and passing CreateOffScreen a rectangle with a nonzero coordinate ° d ONLN dñ }à â˙ ( •Í
in the top ° d ONLN d† }˙ Ⲡ).- ° d ONLN d° â < ï ( ± Z left corner is an easy way to ° d ONLN dø â ï˙ )é>do this. The coordinate system can be translated after the off ° d ONLN d˝ â˙ ï˛ ( ±- ° d ONLN d˛ ï < °: ( Ω Z4screen graphics environment is created by using the ,
Courier
° d ONLN d2 ï: °v )˛
_SetOrigin
° d ONLN d< ïv °˛ )< routine that’s described on ° d ONLN dY ° < ≠ π ( … Zpages 153 through 155 of ° d ONLN dr ° π ≠
)}Inside Macintosh ° d ONLN dÉ °
≠ )TV ° d ONLN dÑ ° ≠< )olume I. ° d ONLN dç π < ≈ p ( · ZWarning: ° d ONLN dñ π Ñ ≈ ï )HAs ° d ONLN dô π ï ≈ Î )Inside Macintosh ° d ONLN d™ π Î ≈ Û )VV ° d ONLN d´ π Ú ≈Ω )*olume I, page 154, notes, the clip region ° d ONLN d’ πΩ ≈⁄ )Àof the ° d ONLN d‹ ≈ Ñ — õ ( Ì ¢port ° d ONLN d· ≈ õ —ç )0“sticks” to the coordinate system when you call
, you should ° d ONLN d˝ ı⁄ )B,set the clip region so that you can continue ° d ONLN d* Ñ
Î () ¢drawing into the port. ° d ONLN dA <%6 (A Z1The number of bits per pixel implies the maximum ° d ONLN dr6%˛ )˙(number of available colors in a graphics ° d ONLN dõ% <1 … (M Z environment, at least roughly ° d ONLN dπ% …1˛ )ç?speaking. The relationship between the number of bits per pixel ° d ONLN d˘1 <= a (Y Zand the ° d ONLN d1 a=· )%Nnumber of available colors is discussed in the “Graphics Overview” chapter of ° d ONLN dO1·=˛ (YˇInside ° d ONLN dV= <I p (e Z
Macintosh ° d ONLN d`= pI x )4V ° d ONLN da= wI# )"olume VI, pages 16-8 through 16-9. ° d ONLN dÑU <a U (} ZIf an ° d ONLN däU Ua˛ )Vindexed-color graphics environment is being made, then a color table must be passed to ° d ONLN d·a <mõ (â ZKCreateOffScreen. In ExerciseOffScreen, the color table is retrieved from a ° d ONLN d,aõm˛ (âπ'clut' resource that’s ° d ONLN dCm <y ò (ï Zin the application’s ° d ONLN dXm òy )\ resource fork with a call to
° d ONLN dum y[ )á
_GetCTable
° d ONLN dm[y˛ )< . Because CreateOffScreen clones ° d ONLN d†y <ÖW (° Z@this color table, this 'clut' resource can be purgeable so that ° d ONLN d‡yWÖ˛ (°u"it can be thrown out if its memory ° d ONLN dÖ <ë … (≠ Z is needed for other purposes.
° d ONLN d ˙ÕËŸ˛ )< and ° d ONLN d ˇŸ < ü ( Zthen initializing it by ° d ONLN d
Ÿ ü ‘ )c
hand. The
° d ONLN d
!Ÿ ‘Â )5
ColorTable
° d ONLN d
+ŸÂ˛ )</ structure is documented on pages 48 through 49 ° d ONLN d
[Â <Ò I (
Zof ° d ONLN d
^Â IÒ ù )
Inside Macintosh ° d ONLN d
o ùÒ • )TV ° d ONLN d
p §Ò ƒ )olume ° d ONLN d
v ƒÒ à ) V ° d ONLN d
w ÀÒØ )2. Here’s what each of the fields should be set to:
° d ONLN d
™˝ < ` (% ZctSeed
° d ONLN d
±˝ ®
)lidentification value. ° d ONLN d
«˝
˛ )b1This is an arbitrary value that should be changed ° d ONLN d
˘ ® º (1 Δany ° d ONLN d
˝ º˛ )Etime the contents of the color table change so that the inverse table ° d ONLN d C ®! Ï (= Δ can be kept ° d ONLN d O Ï!˛ )D0current. When Color QuickDraw draws anything, it ° d ONLN d Ä! ®- Ì (I Δ
compares the
° d ONLN d ç! Ì- )EctSeed
° d ONLN d ì!-í )$ of the color table of the
° d ONLN d Æ!í-∂ )ÅPixMap
° d ONLN d ¥!∂-› )$ of the ° d ONLN d º!›-˛ )'current
° d ONLN d ƒ- ®9 “ (U ΔGDevice
° d ONLN d À- “9
)*
against the
° d ONLN d ÿ-
9= );iTabSeed
° d ONLN d ‡-=9† )0 field of the inverse ° d ONLN d ˆ-†9˛ )ctable of the current
° d ONLN d 9 ®E “ (a ΔGDevice
° d ONLN d 9 “E ‹ )*. ° d ONLN d 9 ‹E˛ )
5If they’re the same, then Color QuickDraw uses colors ° d ONLN d JE ®Q (m Δaccording to that ° d ONLN d \EQ˛ )`/inverse table. If they’re different, then Color ° d ONLN d åQ ®] ˘ (y ΔQuickDraw first ° d ONLN d úQ ˘]˛ )Q5rebuilds the inverse table according to the new color ° d ONLN d “] ®i (Ö Δtable’s contents and its
° d ONLN d Î]iJ )riTabSeed
° d ONLN d Û]JiZ )0 is ° d ONLN d ˜]Zi˛ )!set to the value of the new color ° d ONLN d
i ®u (ë Δtable’s
° d ONLN d
!i u Ó )"ctSeed
° d ONLN d
'i Óu† )$); then the rebuilt inverse table is used. ¡ X¡
of 51 (Ï ZM.QD.PrincipiaOffScreen ˇ$l ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d Ñ ) £ +lWhen ,
Courier
° d ONLN d £ ) Ÿ ) _CopyBits
° d ONLN d Ÿ ). )6 is called with the
° d ONLN d " . )X )UsrcCopy
° d ONLN d ) X )Ç )*
transfer ° d ONLN d 3 Ç )∂ )*
mode, the
° d ONLN d = ∂ )⁄ )4ctSeed
° d ONLN d D ) Ñ 5 · ( Q ¢fields of the source ° d ONLN d Y ) · 5⁄ )]3and destination pixel maps are compared. If they’re ° d ONLN d ç 5 Ñ A — ( ] ¢the same, then
° d ONLN d ú 5 — A )M _CopyBits
° d ONLN d • 5 A⁄ )6* simply transfers the source pixels to the ° d ONLN d – A Ñ M Ì ( i ¢destination with no ° d ONLN d ‰ A Ì M⁄ )i-mapping of colors. If they’re different, then
° d ONLN d M Ñ Y ∫ ( u ¢ _CopyBits
° d ONLN d M ∫ YS )6 checks each entry of the color ° d ONLN d; MS Y⁄ )ôtables to determine whether ° d ONLN dW Y Ñ e ( Å ¢they have the same colors ° d ONLN dq Y e⁄ )Å+for the same pixel values. If they do, then
° d ONLN dù e Ñ q ∫ ( ç ¢ _CopyBits
° d ONLN d¶ e ∫ q € )6 again ° d ONLN d≠ e € q⁄ )!5simply transfers the source pixels to the destination ° d ONLN d„ q Ñ } ‰ ( ô ¢with no mapping of ° d ONLN dˆ q ‰ }f )` colors. If they don’t, then
° d ONLN d qf }ú )Ç _CopyBits
° d ONLN d qú }⁄ )6 maps colors ° d ONLN d( } Ñ â Δ ( • ¢in the source
° d ONLN d6 } Δ â Í )BPixMap
° d ONLN d< } Í âr )$ to the colors in the current ° d ONLN dZ }r â⁄ )àgraphics environment ° d ONLN do â Ñ ï ( ± ¢ according to the inverse table ° d ONLN dé â ïU )åof the current
° d ONLN dù âU ï )EGDevice
° d ONLN d§ â ïù )*. The
° d ONLN d™ âù ï¡ ) ctSeed
° d ONLN d∞ â¡ ï⁄ )$ field ° d ONLN d∑ ï Ñ °g ( Ω ¢0of a color table should be changed whenever its ° d ONLN dÁ ïg °⁄ )„contents are changed so ° d ONLN dˇ ° Ñ ≠ ò ( … ¢that
° d ONLN d ° ò ≠ Œ ) _CopyBits
° d ONLN d
° Œ ≠F )6 doesn’t make the wrong ° d ONLN d% °F ≠⁄ )x assumptions about the equality ° d ONLN dD ≠ Ñ πH ( ’ ¢+of the source and destination color tables. ° d ONLN dq ≈ Ñ — å *Y ° d ONLN dr ≈ ã — )
ou can get a ° d ONLN d ≈ —⁄ )?7seed value for a new color table by assigning to it the ° d ONLN d∑ — Ñ › ¬ ( ˘ ¢result of the
È )VV ° d ONLN d › È5 )olume ° d ONLN d ›5 È= )!V ° d ONLN d ›< È⁄ )!, page 143. If the contents of an ° d ONLN dA È Ñ ıª ( ¢;existing color table are changed, then it should be passed ° d ONLN d| Ȫ ı⁄ (Ÿto the
° d ONLN dÉ ı Ñ Ã ( ¢ _CTabChanged
° d ONLN dè ı Ãé )H* routine which assigns a new value to its
° d ONLN dπ ıé≤ )¬ctSeed
° d ONLN dø ı≤µ )$ ° d ONLN d¿ ıµ⁄ ) field. If ° d ONLN d Ñ
ò () ¢the
° d ONLN dŒ ò
‡ ) _CTabChanged
° d ONLN d⁄ ‡
p )H routine isn’t available (it’s ° d ONLN d˘p
⁄ )êavailable with 32-Bit ° d ONLN d
Ñπ (5 ¢9QuickDraw and is included with the system beginning with ° d ONLN dH
π⁄ (5◊system ° d ONLN dO Ñ%# (A ¢ software version 7.0), then the
° d ONLN do#%G )üctSeed
° d ONLN duG%õ )$ field should be ° d ONLN dÜõ%⁄ )T given a new ° d ONLN dí% Ñ1 ˝ (M ¢value with another call to
° d ONLN d≠% ˝19 )y
_GetCTSeed
° d ONLN d∑%91= )<.
° d ONLN dπ= I B (e 6ctFlags
° d ONLN d¡= ÑIù )l8indicates the Boolean characteristics of a color table. ° d ONLN d˘=ùI⁄ (eª If the most ° d ONLN dI ÑU ‡ (q ¢significant bit of
° d ONLN dI ‡U
)\ctFlags
° d ONLN d I
Uq )* is clear, then the
° d ONLN d3IqUè )gvalue
° d ONLN d8IèUñ ) ° d ONLN d9IñU⁄ )
field of each
° d ONLN dGU Ña ∫ (} ¢ ColorSpec
° d ONLN dPU ∫a ˘ )6 entry in the
° d ONLN d^U ˘a# )?ctTable
° d ONLN deU#a• )* array is interpreted as the ° d ONLN dÇU•a⁄ )Ç pixel value ° d ONLN déa Ñm ñ (â ¢for ° d ONLN día ñm5 )"the color that’s specified in the
° d ONLN d∫¡≥Õ⁄ ) field of ° d ONLN dƒÕ ÑŸ ú (ı ¢each
° d ONLN d…Õ úŸ “ ) ColorSpec
° d ONLN d“Õ “Ÿ ’ )6 ° d ONLN d”Õ ’Ÿ )record in the
° d ONLN d·ÕŸ@ )ActTable
° d ONLN dËÕ@Ÿñ )* array is used by
° d ONLN d˙ÕñŸÃ )V _CopyBits
° d ONLN d Õß⁄ )6 as ° d ONLN d Ÿ Ñ ( ¢an index into the color ° d ONLN d Ÿ ÂŒ )l0palette that’s attached to the destination windo ° d ONLN d OŸŒÂ◊ )fiw ° d ONLN d PŸ÷Â⁄ ), ° d ONLN d R ÑÒ ± (
¢and the
° d ONLN d ZÂ ±Ò √ )-rgb
° d ONLN d ] √Òè )& field is ignored. This is documented ° d ONLN d ÉÂèÒ⁄ )Ãin the “Palette ° d ONLN d ìÒ Ñ˝ Á ( ¢Manager” chapter of ° d ONLN d ßÒ Á˝; )cInside Macintosh ° d ONLN d ∏Ò;˝C )TV ° d ONLN d πÒB˝Æ )olume VI, page 20-17. ° d ONLN d – Ñ ∂ (1 ¢
The other ° d ONLN d ⁄ ∂⁄ )2=bits are reserved for future use. If you create a color table ° d ONLN d
Ñ! (= ¢from scratch, these other ° d ONLN d
2 !⁄ )|,bits must be set to zero. If you use a color ° d ONLN d
_! Ñ-“ (I ¢Htable that’s generated by the system, then these bits must be preserved.
° d ONLN d
®9 E < (a 6ctSize
° d ONLN d
Ø9 ÑE º )l the number ° d ONLN d
∫9 ºEy )8'of color table entries minus 1. Normall ° d ONLN d
·9yE )Ωy ° d ONLN d
‚9~E⁄ ), this field is set to ° d ONLN d
˘E ÑQ ¥ (m ¢
1, 3, 15, ° d ONLN d E ¥Q¬ )08or 255 for 1-, 2-, 4-, and 8-bits per pixel, respectivel ° d ONLN d ;E¬Q» (m‡y ° d ONLN d <E«Q⁄ ). In ° d ONLN d AQ Ñ] (y ¢ special cases, it’s reasonable ° d ONLN d `Q]⁄ )ä'to have less than the maximum number of ° d ONLN d à] ÑiU (Ö ¢,entries for the pixel depth. For example, a ° d ONLN d ¥]Ui⁄ )— color table for an 8-bit per ° d ONLN d —i ÑuW (ë ¢+pixel graphics environment could have just ° d ONLN d ¸iWu⁄ )”150 entries, in which case ° d ONLN d u ÑÅ ñ (ù ¢the
° d ONLN d ® )N ( E Δ$entries for a pixel depth and clear ° d ONLN d $ N )˛ )¶$the entries you’re not using to zero ° d ONLN d I ) ® 5√ ( Q Δ9because some parts of Color QuickDraw assume the size of ° d ONLN d Ç )√ 5˛ ( Q·
a color table ° d ONLN d ê 5 ® A ( ] Δbased on the pixel depth. ,
Courier
° d ONLN d ™ M < Y f ( u ZctTable
° d ONLN d ≤ M ® Y )larray of colors and ° d ONLN d Δ M Y˛ )d2pixel values. This table defines all the available ° d ONLN d ˘ Y ® e  ( Å Δcolors in the ° d ONLN d Y  e† )=(color table and their pixel values. The
° d ONLN d/ Y† eæ )ªvalue
° d ONLN d4 Yæ e˛ ) field of each
° d ONLN dC e ® q fi ( ç Δ ColorSpec
° d ONLN dL e fi qû )6% record indicates that color’s pixel ° d ONLN dq eû q˛ )¿value if the most ° d ONLN dÉ q ® } ¯ ( ô Δsignificant bit of
° d ONLN dñ q ¯ }" )PctFlags
° d ONLN dù q" }¢ )* is clear. It’s ignored if the ° d ONLN dº q¢ }˛ )Ämost significant bit ° d ONLN d— } ® â µ ( • Δof
° d ONLN d‘ } µ â fl )
ctFlags
° d ONLN d€ } fl â )*
is set. The
° d ONLN dË } â8 );value
° d ONLN dÌ }8 Ⲡ) , field is used as an index into a palette if ° d ONLN d â ® ï@ ( ± Δ!the next most significant bit of
° d ONLN d; â@ ïj )òctFlags
° d ONLN dB âj ïz )* is ° d ONLN dF âz ïÏ )set, in which case the
° d ONLN d] âÏ ï˛ )rrgb
° d ONLN da ï ® °v ( Ω Δ,field is ignored. See the discussion of the
° d ONLN dç ïv °† )ŒctFlags
° d ONLN dî ï† °Ω )* field ° d ONLN dõ ïΩ °˛ ) earlier in this ° d ONLN d´ ° ® ≠ ( … ΔNote for more details. ° d ONLN d¬ π < ≈ p ( · ZWarning: ° d ONLN dÀ π Ñ ≈L )H(Color QuickDraw’s text-drawing routines ° d ONLN dÛ πL ≈⁄ )» assume that the color table of ° d ONLN d ≈ Ñ — ò ( Ì ¢the ° d ONLN d ≈ ò —⁄ ):destination graphics environment has the maximum number of ° d ONLN dQ — Ñ › ( ˘ ¢"colors for the pixel depth of the ° d ONLN ds — ›⁄ )ó'graphics environment, and that white is ° d ONLN dõ › Ñ È% ( ¢#the first entry in the color table ° d ONLN dæ ›% È• )°and black is the last entr ° d ONLN dÿ ›• È´ )Äy ° d ONLN dŸ ›™ È⁄ )
. If these ° d ONLN d‰ È Ñ ı≈ ( ¢Gconditions aren’t satisfied, then the resulting image is unpredictable. ° d ONLN d, <
() Z)The code fragment in Listing 6 shows how ° d ONLN dU
˛ )÷1to allocate a 256-entry color table from scratch. ° d ONLN dá
< (5 Z*Color tables have a variable size, so the
° d ONLN d±
E )Õ
_NewHandle
° d ONLN dª
E˛ )<& call has to calculate the size of the
° d ONLN d‚ <% x (A Z
ColorTable
° d ONLN dÏ x%Δ )<? record plus the maximum number of color table entries for the ° d ONLN d+Δ%˛ (A‰ pixel depth ° d ONLN d7% <1 ƒ (M Z multiplied by the size of a
° d ONLN dS% ƒ1 ˙ )à ColorSpec
° d ONLN d\% ˙1 ˇ )6 ° d ONLN d]% ˇ1' )record.
° d ONLN de%'1c )(
kNumColors
° d ONLN do%c1˛ )< - 1 is used in the calculation ° d ONLN dè1 <= d (Y Zbecause ° d ONLN dó1 d= ¨ )(the size of the
° d ONLN dß1 ¨= Ë )H
ColorTable
° d ONLN d±1 Ë=Ñ )<! record includes the size of one
° d ONLN d“1Ñ=∫ )ú ColorSpec
° d ONLN d€1∫=˛ )6 entry in most ° d ONLN dÍ= <I ø (e Zdevelopment environments. ° d ONLN dU <a ∫ *MPW Pascal Listing 6
° d ONLN dm <x U *CONST ° d ONLN d w <Ç@ *
4 kNumColors = 256; {Number of color table entries} ° d ONLN dTã <ñ K *VAR ° d ONLN dXï <†Y *
9 newColors: CTabHandle; {Handle to the new color table} ° d ONLN díü <™^ *
: index: Integer; {Index into the table of colors} ° d ONLN dÕ≥ <æ *)(* Allocate memory for the color table *) ° d ONLN d˜Ω <»h *
° d ONLN d 5 @: *:#define kNumColors 256 /* Number of color table entries */ ° d ONLN d K I T5 *9CTabHandle newColors; /* Handle to the new color table */ ° d ONLN d Ö S ^: *
:short index; /* Index into the table of colors */ ° d ONLN d ¿ g r  *)/* Allocate memory for the color table */ ° d ONLN d Í q |I *
=newColors = (CTabHandle)NewHandleClear( sizeof (ColorTable) + ° d ONLN d( { Ü *
0 sizeof (ColorSpec) * (kNumColors - 1) ); ° d ONLN dY Ö ê Å *
* (**newColors).ctSize = kNumColors - 1; ° d ONLN d À ÷ ‡ *( /* Initialize the table of colors */ ° d ONLN d, ’ ‡ *
0 for (index = 0; index < kNumColors; index++) ° d ONLN d] fl Í 1 *
{ ° d ONLN dc È Ù *
3 (**newColors).ctTable[index].value = index; ° d ONLN dó Û ˛D *
< (**newColors).ctTable[index].rgb.red = someRedValue; ° d ONLN d‘ ˝ X *
@ (**newColors).ctTable[index].rgb.green = someGreenValue; ° d ONLN d N *
> (**newColors).ctTable[index].rgb.blue = someBlueValue; ° d ONLN dT 1 *
} ° d ONLN dZ & *
}
° d ONLN d\1 = R * Changing ° d ONLN de1 R= [ ):Y ° d ONLN df1 Z= π )our Environment ° d ONLN dvI UΔ (q 6WAfter you create an off-screen graphics environment with certain dimensions, you might ° d ONLN dÕIΔU⁄ (q‰later ° d ONLN d”U a ≈ (} 6#want to change its size, depth, or ° d ONLN dˆU ≈a⁄ )≠6color table without creating a completely new graphics ° d ONLN d-a mW (â 67environment from scratch and without needing to redraw ° d ONLN ddaWm⁄ (âuthe existing image. The ° d ONLN d|m y≠ (ï 6MUpdateOffScreen routine in Listing 7 shows just one way to do this. It takes ° d ONLN d…m≠y⁄ (ïÀthe same ° d ONLN d“y Öê (° 6Lparameters that CreateOffScreen (defined in Listing 1) does, but instead of ° d ONLN d yêÖ⁄ (°Æcreating a new
° d ONLN d-Ö ë N (≠ 6 CGrafPort
° d ONLN d6Ö Në m )6 and
° d ONLN d;Ö më ó ) GDevice
° d ONLN dBÖ óë Ø )*, it ° d ONLN dGÖ Øëó )*alters the ones that you pass through the
° d ONLN dqÖóë¡ )ËupdPort
° d ONLN dxÖ¡ë⁄ )* and
° d ONLN d}ë ù T (π 6
updGDevice
° d ONLN dáë Tù ü )< parameters. If ° d ONLN dóë üù ≤ )Kthe
% HNoPurge(Handle(newColors)); ° d ONLN dc≠ <∏ Õ *
colors := newColors; ° d ONLN dÅ∑ <¬ n *
END; ° d ONLN dåÀ <÷ü *G (* Calculate the number of bytes per row in the off-screen PixMap *) ° d ONLN d‘’ <‡≥ *
K bytesPerRow := ((depth * (bounds.right - bounds.left) + 31) DIV 32) * 4; ° d ONLN d È <Ù ** (* Get the current QuickDraw version *) ° d ONLN dKÛ <˛Y *
END; ° d ONLN d– Ô < ˙; *3 (* Restore the given state of the color table *) ° d ONLN d ˘ < ¥ *
IF colors <> NIL THEN ° d ONLN d < *
, HSetState(Handle(colors), savedState); ° d ONLN dJ <"E *5 (* One Last Look Around The House Before We Go… *) ° d ONLN dÄ! <, π *
IF error <> noErr THEN ° d ONLN dö+ <6 s *
BEGIN ° d ONLN d¶5 <@ · *
! IF newPixMap <> NIL THEN ° d ONLN d»? <J ë *
BEGIN ° d ONLN d⁄I <T1 *
1 IF newPixMap^^.pmTable <> NIL THEN ° d ONLN d S <^@ *
4 DisposCTable(newPixMap^^.pmTable); ° d ONLN dA] <h6 *
2 IF newPixMap^^.baseAddr <> NIL THEN ° d ONLN dtg <r6 *
2 DisposPtr(newPixMap^^.baseAddr); ° d ONLN dßq <|' *
/ DisposHandle(Handle(newPixMap)); ° d ONLN d◊{ <Ü å *
END; ° d ONLN dËÖ <ê n *
END; ° d ONLN dÛè <ö » *
UpdateOffScreen := error; ° d ONLN dô <§ P *
END;
° d ONLN dØ <ª ü *MPW C Listing 7
° d ONLN d%« <“∏ *L#define kMaxRowBytes 0x3FFE /* Maximum number of bytes in a row of pixels */ ° d ONLN dr€ <Ê ™ *OSErr UpdateOffScreen( ° d ONLN dâ <ï *
E Rect *newBounds, /* New bounding rectangle of off-screen */ ° d ONLN dœÔ <˙≥ *
K short newDepth, /* New number of bits per pixel in off-screen */ ° d ONLN d˘ <§ *
H CTabHandle newColors, /* New color table to assign to off-screen */ ° d ONLN dd <≥ *
K CGrafPtr updPort, /* Returns a pointer to the updated CGrafPort */ ° d ONLN d∞
<§ *
H GDHandle updGDevice) /* Returns a handle to the updated GDevice */ ° d ONLN d˘ <" A *
{ ° d ONLN d˚! <,ü *
G PixMapHandle newPixMap; /* Handle to the new off-screen PixMap */ ° d ONLN dC+ <6ü *
G PixMapHandle oldPixMap; /* Handle to the old off-screen PixMap */ ° d ONLN dã5 <@ê *
D Rect bounds; /* Boundary rectangle of off-screen */ ° d ONLN d–? <JÜ *
& HNoPurge( (Handle)newColors ); ° d ONLN dl+ 6 ü *
colors = newColors; ° d ONLN dà5 @ 1 *
} ° d ONLN déI TÄ *H /* Calculate the number of bytes per row in the off-screen PixMap */ ° d ONLN d◊S ^ä *
J bytesPerRow = ((depth * (bounds.right - bounds.left) + 31) >> 5) << 2; ° d ONLN d"g r Ô *+ /* Get the current QuickDraw version */ ° d ONLN dNq |5 *
9 (void)Gestalt( gestaltQuickdrawVersion, &qdVersion ); ° d ONLN dàÖ ê£ *O /* Make sure depth is indexed or depth is direct and 32-Bit QD installed */ ° d ONLN dÿè öS *
? if (depth == 1 || depth == 2 || depth == 4 || depth == 8 || ° d ONLN dô §ä *
